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Preface 


Organization 


This publication is a reference manual and contains the macro instructions that 
are used for the virtual storage access method (VSAM). It is intended for 
programmers who use VSAM macro instructions, access method services 
commands, or JCL to process data. 


This publication contains the following major scctions: 


e Chapter I, “Macro Instruction Return Codes and Reason Codes,” contains 
return codes for macros used to open and close data sets, manage control 
blocks, and issue data management requcsts. 


e Chapter 2, “VSAM Macro Formats and Examples,” describes the syntax of 
each macro and includes coded examples. 


¢ Appendix A, “Format of Macros,” summarizes, for ease of reference, the 
format of the macros used to communicate with VSAM. 

© Appendix B, “List, Execute, and-Generate Ferms of Macros,” explains how | 
to code reentrant programs with the macros that generate, modify, test, and 
display control blocks at execution. 


¢ Appendix C, “Operand Notation,” defines the terms used to describe the 
operand notation used in the macros that generate, modify, test, and display 
control blocks at program execution time. 


e Appendix D, “Building Parameter Lists,” describes the standard way to 
build parameter lists. 


e “Glossary of Terms and Abbreviations” defines VSAM terms. 


@ Index is a subject index to this publication. A 
| 
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Prerequisite Knowledge 


Readers of this publication are assumed to have a programming background that 
includes: 


e 


e@ 


VSAM data management 
Catalog administration 


Job control language 


Required Publications 


You should be familiar with the information presented in the following 
publications: 


e 


Related Publications 


MVS|/Extended Architecture Catalog Administration Guide, GC26-4138, 

describes the administration of tasks for catalogs and how to use the access 
method services commands to manipulate catalogs, and the objects cataloged | 
in them. : 


MVS]/Extended Architecture Data Facility Product Version 2: Customization, 
GC26-4267, contains consolidated customization information for the DFP 


_ library. 


MVS/Extended Architecture JCL User's Guide, GC28-1351, and 
MVS]/Extended Architecture JCL Reference, GC28-1352, describes the JCL 
parameters referred to in this publication and describes dynamic allocation. 


MVS/Extended Architecture Message Library: System Messages, Volumes 1 
and 2, GC28-1376 and GC28-1377, provides a complete listing of the 
messages issued by VSAM. 


. MVS/Extended Architecture VSAM Administration Guide, GC26-4151, 


describes how to use VSAM. 


MVS]/Extended Architecture VSAM Logic, LY26-3970, describes the internal 
logic of VSAM. 


Within the text, references are made to the publications listed in the table below: 


iV MVS/XA VSAM Administration: Macro Instruction Reference 





Order Number 
GC26-4135 | 






Short Title Publication Title 


Access Method MVS/Extended Architecture 
Services Integrated Catalog 

Reference Administration: Access Method 
Services Reference 



























MVS]/Extended Architecture GC26-4136 


VSAM Catalog 
| Administration: Access Method 
Services Reference 


Catalog MVS/Extended Architecture GC26-4138 
Administration Catalog Administration Guide 

Guide 

Checkpoint/ MVS/Extended Architecture GC26-4139 
Restart User’s Checkpoint/ Restart User's 

Guide Guide 


Data Facility MVS]/Extended Architecture GC26-4267 
Product: Data Facility Product Version 

Customization 2: Customization 

Reference 


Data MVS/Extended Architecture GC26-4141 
Data 


Administration: Data Administration: Macro 
MVS/Extended Architecture LYB8-1191 
Areas — JES2 Data Areas~— JES 2 



























Macro Instruction Reference 
Instruction 


Data MVS/Extended Architecture LYB8-1195 
Areas — JES3 Data Areas—JES 3 
Data Facility MVS]/Extended Architecture GC26-4146 
Product: Master Data Facility Product Version 
Index 2: Master Index 

| Data Facility MVS/Extended Architecture | GC26-4147 
Product: Data Facility Product Version 


Planning Guide 2: Planning Guide 


Debugging MVS]/Extended Architecture 
Handbook System Programming Library: 
Debugging Handbook, 
Volumes 1 through 5 


















LC28-1164! 
LC28-1165 
LC28-1166 
LC28-1167 
LC28-1168 


GA32-0028 















Introduction to the IBM 3850 
Mass Storage System (MSS) 


Introduction to 
the IBM 3850 
Mass Storage 
System 


JCL User’s MVS/Extended Architecture GC28-1351 

Guide JCL User's Guide 

JCL Reference MVS/Extended Architecture GC28-1352 
JCL Reference 


Note: 








1 All five volumes may be ordered under one order number, LBOF-1015. 
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Supervisor 


Storage System (MSS) Services: Reference 

RACF General ‘OS/VS2 MVS Resource Access | GC28-0722 
Information Control Facility (RACF): 

Manual General Information Manual 

Services and 

Macro 


Services: Information 
MVS/Extended Architecture GC28-1154 
Instructions Instructions | 
d 


Short Title Publication Title Order Number 
Reference 
System Programming Library: 
System Messages MVS]/Extended Architecture GC28- 1376 
Message Library: System an 
Messages, Volumes | and 2 GC28-1377 


OS/VS Mass OS/VS Mass Storage System GC35-0017 
Information 

Supervisor Services and Macro 
System | MVS/Extended Architecture GC28-1152 
Modifications - System Programming Library: 

System Modifications 












rSO Command OS/VS2 TSO Command GC28-0646 
Language Language Reference with S$D23-0259 
Reference MVS/Extended Architecture 










supplement 
TSO Terminal MVS/Extended Architecture GC28-1274 
User’s Guide TSO Terminal User's Guide 
VSAM MVS/Extended Architecture GC26-4151 
Administration VSAM Administration Guide 
Guide | 
VSAM Logic MVS/Exiended Architecture LY 26-3970 

VSAM Logic 

31-Bit MVS/Extended Architecture GC28-1158 
Addressing 


System Programming Library: 
Notational Conventions 

















3/-Bit Addressing 


A uniform system of notation describes the format of VSAM macro instructions. 
This notation is not part of the language; it mercly provides a basis for describing 
the structure of the macros. 

The macro format illustrations in this book use the following conventions: 


e Brackets [ ] indicate optional parameters. - 


© Braces { } indicate a choice of entry; unless a default is indicated, you must 
choose one of the entries. 


e Items separated by a vertical bar (|) represent alternative items. No more 
than one of the items may be selected. 


Vi MVS/XA VSAM Administration: Macro Instruction Reference 


An ellipsis (...) indicates that multiple entries of the type immediately 
preceding the ellipsis are allowed. 


Other punctuation (parentheses, commas, etc.) must be entered as shown. 


BOLDFACE type indicates the exact characters to be entered. Such items 
must be entered exactly as illustrated (in uppercase, except in TSO). 


Italics type specifies ficlds to be supplied by the user. 


BOLDFACE-UNDERSCORED type indicates a default option. If the 
parameter is omitted, the underscored boldface value is assumed. 


A‘ ’1in the macro format indicates that a blank (an empty space) must be 
present before the next parameter. 
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Vii 


Summary of Changes 


| Release 3.0, June 1987 


| New Programming Support 


| e Anew parameter, MODE = 24)31, has been added to the BLDVRP, 
| CLOSE, DLVRP and OPEN macros. 


| e Anew parameter, RMODE3! =(ALL|BUFF|CB|NONEB), has been added to 
| the ACB, BLDVRP, GENCB and MODCB macros. This new parameter 

| replaces the MACRF = AMODE3! subparamcter in the ACB, 

| GENCB-ACB, and MODCB-ACB macros and the LOC parameter in the 

| BLDVRP and GENCB-RPL macros. 


| © Anew spccification, DATA|INDEX, has been added to the TYPE parameter 
| in the BLDVRP macro. 


| 2 A new option, LDS, has been added to the TESTCB-ACB macro. 

| e The parameter LOC = BELOWIANY has been added to the GENCB macro. 
| e The BLDVRP, CLOSE, DLVRP, and OPEN parameter lists, the ACB, and 
| other control blocks and I/O buffers may now reside above or below 16 


| megabytes. 


| @ New codes have been added to the logical error reason codes in the feedback 
| _ ficld of the request parameter list. 


| @ New codes have been added to the return codes from BLDVRP and some 
| existing code descriptions have been changed. 


| e Some code descriptions have been changed in the open reason codes in the 
| error ficld of the access method control block. 


Summary of Changes iX 


Service Changes 


Information has been added to reflect technical service changes. 


Version 2 Publications 


The tables containing the macro operand expressions in Appendix C, “Operand 
Notation” have been deleted. 


Release 2.0, June 1986 


Service Changes 


Information has been added to reflect technical service changes. 


Version 2 Publications 


The preface. has been updated ta include order numbers. for Version 2. 


Release 1.0, April 1985 


A new paramcter, ACTION = REFRESH, has been added to the VERIFY 
macro. 


A new parameter, IOPID, has been added to the EXLST macro. This parameter 
permits termination of existing I/O and prevention of new I/O. 
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Chapter 1. Macro Instruction Return Codes and Reason Codes 


This chapter describes the return codes and reason codes gencrated by the macro 
instructions used to open and close a data set, manage VSAM control blocks, 
and issue data processing requests. 


VSAM sets the return codes in register 15. These return codes are paired with 
reason codes set in the access method control block (ACB) and the request 
parameter list (RPL). Reason codes set in the ACB indicate open or close errors. 
Reason codes set in the RPL indicate record management errors. 


This manual lists return codes and reason codes in decimal and hexadecimal 
valucs. The decimal value is shown first, followed by the hexadecimal value in 
parentheses. Format descriptions and examples of each macro are shown in 
Chapter 2, “VSAM Macro Formats and Examples” on page 33. 


Return Codes and Reason Codes from OPEN 


When your program receives control after issuing an OPEN macro, the return 
code in register 15 indicates whether all of the VSAM data sets were opened 
successfully: 


Return 
Code Condition 


0(0) All data sets were opened successfully. 


4(4) All data sets were opened successfully, but one or more warning 
messages were issued (reason codes less than X’80’). 


8(8) At least one data set (VSAM or non-VSAM) was not opened 
successfully; the access method control block was restored to the 
contents it had before OPEN was issued; or, if the data set was 
already open, the access method control block remains open and 
usable and is not changed. 


12(C) A non-VSAM data set was not opened successfully when a 
non-VSAM and a VSAM data set were being opened at the same 
time; the non-VSAM data control block was not restored to the 
contents it had before OPEN was issued (and the data set cannot be 
opened without restoring the control block). 


Chapter 1. Macro Instruction Return Codes and Reason Codes 1! 


If register 15 contains a nonzero return code, you can use the SHOWCB macro 
to display the corresponding reason code. The SHOWCB macro displays the 
error field in each access method control block specified by the OPEN macro. 
(See “SHOWCB Macro (Display Fields of an Access Method Control Block)” 
on page 133.) Figure 1 lists the reason codes that may appear in this error field. 
VSAM also writes a message to the operator console and to the programmer’s 
listing to explain the error further. For a listing of VSAM messages, sce System 
Messages. 


Reason . 
Code Condition 


0(0) One of the following conditions exists: 


e VSAM is processing the access method control block for some 
other request. 


@ The access mcthod control block address is invalid. 


76(4C) Warning message: The interrupt recognition flag (IRF) was detected 
for a data sct opencd for input processing. 


92(S5C) Warning message: Inconsistent use of CBUF processing. Sharing 
- aptions differ between index and-data components. 


96(60) Warning message: An unusable data set was opencd for input. 


100(64) § Warning message: OPEN encountered an empty alternate index that 
is part of an upgrade set. 


104(68) | Warning message: The time stamp of the volume on which a data sct 
is stored doesn t match the system time stamp in the data sct’s catalog 
record; this indicates that extent information in the catalog record 
may not agrce with the extents indicated in the volume’s VIOC. 


108(6C) | Warning message: The time stamps of a data component and an 
index component do not match; this indicates that cither the data or 
the index has been updated separatcly from the other. 


116(74) | Warning message: The data set was not properly closed and cither 
OPEN’s implicit verify was unsuccessful or the user specified that 
OPEN’s implicit verify should not be exccuted. 


A previous VSAM program may have abnormally terminated. Data 
may be lost if processing continues; the access method services 
VERIFY command may be used to cause the data set to be properly 
closed. For a description of the VERIFY command, sce Access 
Method Services Reference. In a cross-system shared DASD 
environment, a return code of 116 can have two meanings: (1) the 
data set was not properly closed, or (2) the data set is opened for 
output on another processor. 


=<» 118(76) | Warning message: The data set was not properly closed but OPEN’s 
implicit verify was successfully executed. 


Figure 1 (Part 1! of 4). OPEN Reason Codes in the ERROR Field of the Access 
Method Control Block 
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Reason 
Code 
128(80) 


132(84) 


136(88) 


140(8C) 
144(90) 


145(91) 


148(94) 


152(98) 


160(A0) 


Condition 


DD statement for this access method control block is missing or 
invalid. 


One of the following errors occurred: 


e Not enough storage was available for work areas. 

@ The required volume could not be mounted. 

@ An uncorrectable I/O error occurred while VSAM was reading 
the job file contro] block (JFCB). 

@ The format-1 DSCB or the catalog cluster record is invalid. 

e The user-supplicd catalog name docs not match the name on the 
entry. 

e The user is not authorized to open the catalog as a catalog. | 


Not enough virtual storage space is available in your program’s 
address space for work areas, control blocks, or buffers. 


The catalog indicates this data sct has an invalid physical record size. 


An uncorrectable I/O error occurred while VSAM was reading or 
wniting a catalog record. 


An uncorrectable error occurred in the VSAM volume data sct 
(VVDS). 


No record for the data sct to be opened was found in the available 
catalog(s), or an unidentified error occurred while VSAM was 
searching the catalog. For the catalog return code, sce system 
message IDC30091 in System Messages. 


Authorization checking has failed for the following reasons: 


1. The password specificd in the access method control block for a 
specified level of access doesn’t match the password in the catalog 
for that level of access. 


2. RACF failure. For the catalog return code, see system message 
IDC3009I in System Messages. 


The operands specified in the ACB or GENCB macro are 
inconsistent either with each other or with the information in the 
catalog record. 


One of these conditions has been detected: 


© For option ACBRST 
— Path processing 
— LSRIGSR 

© For option ACBICI 
— LSRIGSR 
—- KSDS 


Figure 1 (Part 2 of 4). OPEN Reason Codes in the ERROR Field of the Access 


Method Control Block 
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Reason 
Code 


164(A4) 


168(A8) 


176(B0) 


180(B4) 


184(B8) 
188(BC) 


192(C0) 


Condition 


— Path processing 

— Sequence set with data 

— Replicated index 

— Blocksize not equal to CI size 
e For option ACBUBF 

— LSR|GSR 

— ACBCNV not specified 

— ACBKEY specified 

— ACBADR specified 
e For option ACBSDS 

— LSR|GSR 

— Path processing 

— Upgrade processing 
e For option ACBCBIC 

— LSRIGSR 

— ACBICI not specified 
e For miscellaneous options 

— Bufferspace specified and the amount is too small to process 

the data set 
' = Volume not mounted 
— Trying to open an cmpty data set for input 


An uncorrectable I/O error occurred while VSAM was reading the 
volume label. 


The data set was not available for the type of processing you 

specified, or an attempt was made to open a reusable data set with the 
resct option while another user had the data set open. The data set 
may have the INHIBIT attribute specified. 


The data set cannot be opened for CBUF processing because it was 
already opened for non-CBUF processing. Or the data set has 
conflicting CBUF attributes for the data and index components of the 
ACB. 


An error occurred while VSAM was attempting to fix a page of 
virtual storage in real storage. 


A VSAM catalog specificd in JCL either does not exist or is not 
open, and no record for the data set to be opened was found in any 
other catalog. 


An uncorrectable I/O error occurred while VSAM was completing an 
I/O request. 


The data sct indicated by the access method control block is not of 
the type that may be specified by an access method control block. 


An unusable data set was opened for output. 


Figure 1 (Part 3 of 4). OPEN Reason Codes in the ERROR Field of the Access 


Method Control Block 
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Reason 
Code 
193(C1) 
196(C4) 
200(C8) 


204(CC) 


oy 


205(CD) 
208(D0) 
212(D4) 


216(D8) 
220(DC) 


224(E0) 


228(E4) 


WI2AES) 


236(EC) 
240(F0) 


244(F4) 


Condition 


The interrupt recognition flag (IRF) was detected for a data set 
opened for output processing. 


Access to data was requested via an empty path. 


The Format-4 DSCB indicates that the volume is unusable. There ~ 
was an error in CONVERTYV to convert the volume from cither real 
to virtual or virtual to real. 


The ACB MACRF specification is GSR and caller is not operating in 
supervisor protect key 0 to 7, or ACB MACRE spccification is CBIC 
(Control Blocks in Common) and caller is not operating in supervisor 
state with protect key 0 to 7. 


The ACBCATX option or VSAM volume data set OPEN was 
specificd and the calling program was not authorized. 


The ACB MACRF spccification is GSR and caller is using an 
OS/VS1 system. 


The ACB MACREF specification is GSR or LSR and the data set 
requires load mode processing. 


The ACB MACREF specification is GSR or LSR and the key length 
of the data set exceeds the maximum key length specified in 
BLDVRP. 


The ACB MACRF specification is GSR or LSR and the data sct’s 
control interval size exceeds the size of the largest buffer specified in 
BLDVRP. 


Improved control interval processing 1s specificd and the data set 
requires load mode processing. 


The ACB MACREF specification is GSR or LSR and the VSAM 
shared resource table (VSRT) does not exist (no buffer pool is 
available). 


Reset was specified for a nonreusable data sct and the data set is not 
empty. 


A permanent staging error occurred in MSS (ACQUIRE). 


Format-4 DSCB and volume timestamp verification failed during 
volume mount processing for output processing. 


The volume containing the catalog recovery area was not mounted 
and not verificd for output processing. 


Figure 1 (Part 4 of 4). OPEN Reason Codes in the ERROR Field of the Access 


Method Control Block 
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Return Codes from CLOSE 


When your program receives control after it has issued a CLOSE macro, a return 
code in register 15 indicates whether all the VSAM data scts were closed 
successfully: 


Return 
Code Condition 


0(0) All data sets were closed successfully. 
4(4) At least one data set (VSAM or non-VSAM) was not closed 
successfully. 


If register 15 contains 4, you can use SHIOWCB to display the ERROR field in 
each access method control block to find out whether a VSAM data set wasn’t 
closed successfully and why not. (Sce “SHOWCB Macro (Display Fields of an 
Access Method Control Block)” on page 133.) Figure 2 gives the reason codes 
that the ERROR ficld may contain following CLOSE. In addition to these 
reason codecs, VSAM writes a message to the opcrator’s console and the 
programmer’s listing to further explain the error. For a listing of these messages, 
see System Messages. 





Return 
Code Condition 


0(0) No error (set when register 15 contains 0). 
4(4) The data set indicated by the access method control block is already 
closed. 


129(81) | TCLOSE was issued against a media manager’s structure. 


132(84) | An uncorrectable I/O error occurred while VSAM was reading the 
job file control block (JFCB). 


136(88) | Not enough virtual storage was available in your program’s address 
space for a work area for CLOSE. 


144(90) = An uncorrectable I/O crror occurred while VSAM was reading or 
writing a catalog record. 


145(91) = An uncorrectable error occurred in the VSAM volume data sct 
(VVDS). 


148(94) An unidentified error occurred while VSAM was searching the 
catalog. 


Figure 2 (Part 1 of 2). CLOSE Reason Codes in the ERROR Field of the Access 
Method Control Block 
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Return 
Code Condition 


184(B8) An uncorrectable I/O error occurred while VSAM was completing 
outstanding I/O requests. 


236{EC) A permanent destaging error occurred in MSS (RELINQUISH). 
With temporary CLOSE, a destaging error or a staging error 
(ACQUIRE) occurred. . 


Figure 2 (Part 2 of 2). CLOSE Reason Codes in the ERROR Field of the Access 
Method Control Block 


OPEN/CLOSE Message Area for Multiple Reason or Warning 
Messages 


During the execution of an OPEN, CLOSE, or TYPE=T option of CLOSE, 
more than one error condition may be detected. However, the ACB error flag 
field can only accommodate one warning or error condition. In order to receive 
multiple error or warning conditions, you may specify an optional message arca. 
VSAM will accumulate error messages from an OPEN, CLOSE, or TYPE=T 
option in this message area. 


Multiple messages will be supplied when you specify nonzero valucs in the 
MAREA and MLEN parameters of the ACB. If MAREA or MLEN is not 
specified or is zero, no error or warning information is stored into the message 
area. The ACB error flag field is then the only indication for errors or warnings. 
if MAREA and MLEN are specified and if the-message area ‘is too smaii to 
accommodate all messages, the last incoming messages are dropped. However, 
you will be given an indication of the number of warnings and me sages that 
occurred. 


The message area provided by VSAM is subdivided into two parts: 


e The message area header 
e The message list 


Message Area Header 
The message arca header contains statistical, pointer, and general information. Its 


contents are unrelated to the individual messages. The format of the message 
area header is shown in Figure 3 on page 8. 
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Byte 0 Flag Byte 


bit O= 1 Full message area header has 
been stored. 


bitO=0 Only flag byte of message area 
header has been stored. 
(Implies that no messages 
-have been stored.) 


bits 1-7 Reserved (set to binary zcros) 


Bytes 1-2 Length of message area header (includes flag byte 
and length byte) 

Byte 3 Request type code: 
X01’ OPEN 


X’02’ CLOSE 
X’03 =TCLOSE 
Bytes 4-11 ddname. used. for ACB | 


Bytes 12-13 Total number of messages (crror or warning 
conditions) issued by OPEN/CLOSE/TCLOSE 


Bytes 14-15 Number of messages stored by OPEN/CLOSE/TCLOSE 
into message area 


Bytes 16-19 Address of message list, for example, of first 
message in message area 


Figure 3. Format of the Message Area Header 





The function of the ACB error flag field remains unchanged whether or not this 
optional message area is specified. At the end of an OPEN, CLOSE, or 
TCLOSE, this field contains either X'00' (indicating no error or warning 
condition occurred) or a nonzero code. The ACB error flag byte stores the 
nonzero OPEN/CLOSE/TCLOSE reason code corresponding to the error or 
warning condition that occurred with the highest severity. 


Message area header information is only stored when a warning or error 
condition is detected; that is, when the ACB error flag ficld is set to a nonzero 
value. The header information consists of the flag byte only if the message area 
length (MLEN) is not large enough to accommodate the full message area 
header. In this case, bit 0 of the flag byte will be zero. Before accessing the 
message header information (bytes | through 19), test byte 0 to see if more 
information is stored. If MLEN=0, no header information is stored, not even 
the flag byte. If the full message area header is stored, bytes 1 and 2 contain its 
actual length. Your program should be sensitive to this length when interrogating 
the message area header. 
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Message List 


The message list contains individual messages corresponding to detected warning 
or error conditions. Bytes 16 through 19 of the message area header point to the 
location of the message list within the message area. If the message area header is 
not stored completely (bit 0 of byte 0 is 0), the location of the message list is not 
provided. Within the message list, individual messages are stored as a contiguous 
string of variable-length records. Bytes 14 and 15 of the message area header 
contain the number of messages stored. Check for a nonzero stored message 
count before investigating the message list. However, messages may not be 
stored even if the ACB error flag byte contains a nonzero value and the message 
area header bit 0 of byte 0 is 1. For example, no messages will be stored if 
MLEN is not large enough to allow at least one message to be stored. 


The format of the individual messages is given in Figure 4. 


Bytes 0-1 Length of message including these two bytes. 


Byte 2 ACB error flag code corresponding to the error or warning 
condition represented by this message. 


Byte 3 Function type code: 


Specifies which dsname, if any, is stored in bytes 4 through 47 of 
the message. 


X’00’ ~=nodsname stored. Bytes 4-47 of the message contain 
binary zcros. The crror warning condition 1s not clearly 
related to a componcnt, or VSAM was unable to identify 
or obtain the cluster name of the component in error. 
This code is used only if the ddname of the ACB does not 
identify a valid DD statement, or VSAM was unable to 
obtain the dsname contained in-the DD statement. 


X‘01’ ~— dsname containcd in DD statement is stored. The error 
or warning condition 1s not clearly related to a 
component, or VSAM was unable to identify or obtain 
the cluster name of the component in error. 


X’02’ dsname (cluster name) of base cluster stored. Error 
occurred during OPEN/CLOSE/TCLOSE for base 
cluster. 


X’03’ = dsname (cluster name) of alternate index component 
stored. Error occurred during OPEN/CLOSE/TCLOSE 
for alternate index component. 


X‘04’ ~— dsname (cluster name) of member of upgrade set stored. 
Error occurred during OPEN/CLOSE/TCLOSE for this 
member of the upgrade set. 


Bytes 4-47 Binary zeros (function type code = X’00’) or a dsname as described 
by byte 3. 


Figure 4. Format of Individual Messages in Message List 
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Bytes 0 and | of each message specify its actual length. Because messages vary in 
length, you will need to know the actual length of each message in order to do 
your processing. 


Byte 2 of the message contains the ACB error flag code; it does not indicate that 
a dsname has been stored. Depending on the condition that raised the ACB 
error flag code, either no dsname or different types of dsnames (DD, base cluster, 
alternate index, or upgrade set member) may be stored. (The same condition. 
may be detected both when opening the base cluster and when opening a 
member of the upgrade set. For example, an I/O error may occur when trying to 
obtain the dsname for the component in error.) Bytes 4 through 47 of the 
message can contain a dsname, but do not specify its type. Only byte 3 of the 
message specifics whether a dsname has been stored and, if so, its type. 


| Control Block Manipulation Macro Return Codes and Reason Codes 


The GENCB, MODCB, SHIOWCB, and TESTCB macros are executable (unlike 
the ACB, EXLST, and RPL macros). Thcy cause control to be given to V;SAM 
to perform the indicated task. VSAM indicates if the task was completed by a 
return code in register 15: 


Return 
Code Condition 


0(0) Task completed. 
—— 44) Task not completed. 
8(8) An attempt was made to use the execute form of a macro to modify a 


keyword that isn’t in the parameter list. (See Appendix B, “List, 
Execute, and Generate Forms of Macros” on page 171.) 


An error can occur because you specified the operands incorrectly or, if you 
constructed a paramcter list yourself, because the parameter list was coded 
incorrectly. See Appendix D, “Building Parameter Lists” on page 183, for an 
explanation of how to construct parameter lists for GENCB, MODCB, 
SHIOWCB, and TESTCB. 


When cegester-I Fconmtaine 4, scerstct’ ('eentains. a.reasorr' code, indicating. why, 

‘ VberiP co tifdte perform the task... If you construct the parameter list, register 0 
can contain reason codes 1, 2, 3, 10, 14, 20, and 21. Figure 5 on page II 
describes cach reason code that can be rcturncd in register 0. 
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Reason Applicable 
Code Macros! Reason VSAM Couldn’t Perform the Task 


1(1) G,M,S,T The request type (generate, modify, show, or test) is 
invalid. 


2(2) G,M;S,T The block type (access method control block, exit list, or 
request parameter list) is invalid. 


3(3) G,M,S,T Onc of the keyword codes in the parameter list is invalid. 


4(4) M,S,T The block at the address indicated is not of the type you 
indicated (access method control block, exit list, or request 
parameter list). 


5(5) S.T —“ Access method control block ficlds were to be shown or 
tested, but the data set is not open or it is not a VSAM 


data sct. 

6(6) S,T Access method control block information about an index 
was to be shown or tested, but no index was opened with 
the data set. 

7(7) M;S An exit list was to be modificd, but the list was not large 


enough to contain the new entry; or an exit was to be 
modified or shown but the spccificd exit wasn’t in the exit 
list. (With TESTCB, if the specificd exit address isn’t 
present, you get an unequal condition when you test for 
it.) | 


8(8) G There isn’t enough virtual storage in your program’s 
address space to generate the access mcthod control 
block(s), exit list(s), or request parameter list(s) and no 
work area outside your address space was specified. 


X39) GS The work area specified was 100 smaii for generation or 
display of the indicated control block or fields. 


10(A) G,M With GENCB, exit list control block type was specified 
and you specified an exit without without giving an 
address. With MODCB, exit list control block type was 
specified and you specified an exit without giving an 
address; in this case, either active or inactive must be 
specificd, but load cannot be specified. 


11(B) M Either (1) a request paramcter list was to be modificd, but 
the request parameter list defines an asynchronous request 
that is active (that is, no CHECK or ENDREQ has been 
issued on the request) and thus cannot be modified; or (2) 
MODCSB is already issued for the control block, but 
hasn’t yet completed. 





Figure 5 (Part 1 of 2). GENCB, MODCB, SHOWCB, and TESTCB Reason Codes © 
- Returned in Register 0 
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Reason 


Code 
12(C) 


13(D) 


14(E) 


15(F) 


16(10) 


19(13) 


20(14) 


21(15) 


 22(16) 


Applicable 
Macros! 


M 


G,M,T 


GS 


G,M,S,T 


M,S,T. 


S,T 


Reason VSAM Couldn’t Perform the Task. 


An access method control block was to be modified, but 
the data set identified by the access method control block 
is open and thus cannot be modified. 


An exit list was to be modificd, and you attempted to 
activate an exit without providing a new exit address. 
Because the exit list indicated does not contain an address 
for that exit, your request cannot be honored. 


One of the option codes (for MACRF, ATRB, or 
OPTCD) has an invalid combination of option codes 
specified (for example, OPTCD=(ADR, SKP)). 


The work area specified did not begin on a fullword 
boundary. 


A VTAM keyword or subparameter was specified but the 
AM=VTAM parameter was not specificd. AM = VTAM 
must be specified in order to process a VTAM version of 

the control block. 


A keyword was specified which refers.to a field beyond 
the length of the control block located at the address 
indicated. (For example, a VTAM keyword was specified, 
but the control block pointed to was a shorter, 
non-VTAM block.) 


Keywords were specificd which apply only if 
MACRF=LSR or GSR. 


The block to be displayed or tested does not exist because 
the data set is a dummy data set. 


AM=VTAM was specified and the RPL FIELDS 
parameter conflicts with the RPLNIB bit status. Either 
RPLFIELDS = NIB was specified and the RPLNIB was 
off, or RPL FIELDS = ARG was specified and the 
RPLNIB bit was on. 


Figure § (Part 2 of 2). GENCB, MODCB, SIIOWCB, and TESTCB Reason Codes 


Note to Figure 5: 


Returned in Register 0 


1 G=GENCB, M=MODCB, S=SIOWCB, T=TESTCB 
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Record Management Return Codes and Reason Codes 


The following record management macros give return codes and reason codes in 
the feedback arca of the RPL: GET, PUT, POINT, ERASE, CHECK, 
ENDREQ, GETIX, PUTIX, ACQRANGE, CNVTAD, MNTACQ, 
MRKBER, SCHBFR, and WRTBFR. . 


The feedback word in the RPL consists of four bytes: 

Byte Description 

1 Problem determination function (PDF) code. This code is used to locate 
the point in VSAM record management at which a logical error 
condition is recognized. A description of the returned PDF code is 
located in the IDARMRCD macro. 


2 RPL return code. This code is returned in register 15. 


3 Component code. This code specifies the component being processcd 
when the error occurred. 


4 Reason code. This code, when paired with the return code in byte 2, 
specifics the actual reason for either a successful completion or an error. 


Bytes 2 through 4 make up the RPL feedback area. An explanation of the codes 
that appear in these three bytes follows. - 


Bytes 3 and 4 make up the RPL condition codec. An explanation of this code 
also follows. 


The field name of cach byte appears within parentheses in the following figure. 


RPL Feedback Word (4 bytes) 
bite Feedback Area (3 bytes) ' 
/ RPL Condition Code (2 bytes) 


PDF Code Return Code Component Code Reason Code 
CRPLFUNCD) CRPLRTNCD) CRPLCMPON) CRPLERRCD) 





For more information on the RPL feedback word, see VSAM Logic. 


Return Codes (RPLRTNCD) 


The meaning of the return code depends on whether processing is asynchronous 
or synchronous. 
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Asynchronous Request 


Synchronous. Request 


After you issue an asynchronous request for access to a data set, VSAM issues a 
return code in register 15 to indicate whether the request was accepted, as follows: 


Return Code 

(RPLRINCD) Condition 

0(0) Request was accepted. 

4(4) Request was not accepted because the request parameter list 
indicated by the request (RPL= address) was active for another 
request. 


If the asynchronous request was accepted, issue a CHECK after doing your other 
processing so VSAM can indicate in register 15 whether the request was 
completed successfully, set a return code in the feedback area, and exit to any 
appropriate exit routine. If the request was not accepted, you should either wait 
until the other request is complete (for example, by issuing a CHIECK on the 
request parameter list) or terminate the other request (using ENDREQ). Then 
you can reissue the rejected request. 


After a synchronous request, or a CHECK or ENDREQ macro, the return code 
in register 15 indicates whether the request was completed successfully, as follows: 


Return Code 

(RPLRINCD) Condition 

0(0) Request completed successfully. 

4(4) Request was not accepted because the request parameter list 
indicated by the request (RPL= address) was active for another 
request. 

8(8) Logical error; specific error is indicated in the feedback area in 
the RPL. 

12(C) Physical error; specific crror is indicated in the feedback area in 
the RPL. 


Component Codes (RPLCMPON) 


When a logical or physical error occurs, VSAM uses the component code field of 
the RPL to identify the component being processed when the error occurred and 
indicates whether the alternate index upgrade set is correct following the request 
that failed. The component code can be displayed and tested by using the 
SHOWCB and TESTCB macros. The codes and their meanings are given in 


Figure 6 on page 15. 
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Note: The component code (byte 3 of the RPL feedback word) and the reason 
code (byte 4 of the RPL feedback word) make up the 2-byte RPL condition 
code. » 2 


For more information on the RPL feedback word see VSAM Logic. 





Component Code What Was Being 


(RPLCMPON) Processed Upgrade Sct Status 
0(0) Base cluster Correct | 

1(1) Base cluster May be incorrect 
2(2) Alternate index Correct 

3(3) Alternate index May be incorrect 
4(4) Upgrade set Correct 

5(5) Upgrade set May be incorrect 


Figure 6. Component Codecs Provided in the RPL 


| Reason Codes (RPLERRCD) 


The 0, 8, and 12 return codes in register 15 are paired with reason codes in the 
fecdback arca of the request parameter list. 


The reason codes in the feedback area of the request parameter list can be 
examined with the SHOWCB or TESTCB macro. You may code your 
examination routine immediately following the request macro. Logical errors, 
physical errors, and reaching the cnd of the data set ali cause VSAM to exit to 
the appropriate exit routine, if you provide one. 


Coordinate error checking in your program with your error-analysis exit routines. 
If they terminate the program, for instance, you would not need to code a check 
for an error after a request. But if a routine returns to VSAM to continue 
processing, you should chcck register 15 after a request to determine whether 
there was an error. Even though the error was handled by an exit routine, you 
may want to modify processing because of the error. 


Reason Codec (Successful Request) 
When the request is complcted, register 15 is set to indicate the status of the 
requcst. A reason code of 0 indicates successful completion. Nonzero codes are 


set for a variety of other reasons. Figure 7 on page 16 lists these codes and their 
meanings. 
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Reason Code 
(RPLERRCD) 

When Register 

15 = (0) ' Condition 


0(0) Request completed successfully. 


4(4) Request completed successfully. For retrieval, VSAM mounted 
another volume to locate the record; for storage, VSAM allocated 
additional space or mounted another volume. 


8(8) For GET requests, indicates a duplicate alternate key exists 
(applies only when accessing a data set using an alternate index 
that allows nonunique keys); for PUT requests, indicates that a 
duplicate key was created in an alternate index with the 
nonunique attribute. 


12(C) All buffers, except for the buffer just obtained, may have been 
modificd and may need to be written; issuance of WRTBFR 
macro is suggested. 


16(10) The sequence-set record does not have enough space to allow it 
to address all of the control intervals in the control area that 
should contain the record. The record was written into a new 


cantrol area. 
20(14) Data set is not on virtual DASD for 
| CNVTAD/MNTACQ/ACQRANGE request. 
24( 18) Buffer found but not modified; no buffer writes performed. 


28(1C) Control interval split indicator was detected during an addressed 
: GET NUP request. 


32(20) Request deferred for a resource held by the terminated RPL is 
asynchronous and cannot be restarted by TERMRPL. 


36(24) Possible data set error condition was detected by TERMRPL: 


e The request was abnormally terminated in the middle of its 
1/O operation. 


© One of the data/index BUFCs of the string contains data that 
needs to be written (BUFCMW= ON) but it was invalidated 


by TERMRPL. 
40(28) Error in PLH data BUFC pointer was detected by TERMRPL. 
Figure 7. Successful Completion Reason Codes in the Feedback Area of the Request | 
Parameter List 
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Reason Code (Logical Errors) 


If a logical error occurs and you have no LERAD routine (or the LERAD exit is 


inactive), VSAM returns control to your program following the last executed 
‘User-Wnitten-Exit Routines” in Data Facility Product: 

Customization describes the LERAD routine.) The return code in register 15 
indicates a logical error (8), and the feedback area in the request parameter list 


instruction. (‘ 


contains a reason code identifying the error. Register 1 points to the request 
parameter list. 


Figure 8 gives the reason codes shown in the feedback area and explains their 


meanings. 


Reason Code 


(RPLERRCD) 
When Register 


15 = 8(8) 
4(4) 


_sy 88) 


12(C) 


16(10) 


Condition 


End of data set encountcred (during sequcntial or 
skip sequcntial rctricval), or the search argument 

is greater than the high key of the data sct. 

Either no EODAD routine is provided, or one is 
provided, returned to VSAM, and the processing 
program issued another GET. (“‘User-Wnitten-Exit 
Routines” in VSAM Administration Guide describes 
the EODAD routine.) 


You attempted to store a record with a duplicate 
key, or there is a duplicate record for an 
altcmate index with the unique key option. 


A key sequence check was performed and an error was 
detected in one of the following processing 
conditions: 


* For-a key-sequenced data set 
— PUT sequential or skip-sequential processing 
— GET sequential, single string input only 
— GET skip-sequential processing and the previous 
request is not a POINT 
¢ For a relative record data sct 


— GET skip-sequential processing 
— PUT skip-sequential processing 


Record not found, or 
the RBA 1s not found in the buffer pool. 


Figure 8 (Part 1! of 7). Logical Error Reason Codes in the Feedback Area of the 


Request Parameter List 
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Reason Code 
(RPLERRCD) 

When Register 

15 = &(8) Condition 


20(14) The RBA is found, but the buffer is under the exclusive control of 
another request. With this condition, it is possible to also have 
buffers invalidated. Or, the control interval is for a record alrcady 
held in exclusive control by another requester. 


Note: If the RPL message area is correctly specified, the following 
information is returned: 


Offset Length Discussion 


0 4 Address of RPL in exclusive 
control 
4 I Flag Byte: 


X'00'- neither RPL is doing a 
control arca split 


X'‘'01'- current RPL is attempting a_ 
control area spit 


X'02'- other RPL is doing 
a control area split 


24(18) Record resides on a volume that can’t be mounted. 


28(1C) Data set cannot be extended because VSAM can’t allocate 
additional direct access storage space. Either there is not enough 
space Icft to make the secondary allocation request or you 
attempted to increase the size of a data sct while processing with 
SHAREOPTIONS = 4 and DISP=SHR. 


32(20) You specified an RBA that doesn’t give the address of any data 
record in the data set. 

36(24) Key ranges were specified for the data sct when it was defined, but 
no range was specificd that includes the record to be inserted. 

40( 28) Insufficient virtual storage in your address space to complcte the 
request. - 

44(2C) Work area not large enough for the data record or for the buffer. 


(GET with OPTCD= MVE). 


Figure 8 (Part 2 of 7). Logical Error Reason Codes in the Feedback Area of the 
Request Parameter List 
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Reisen Code 


(RPLERRCD) 
When Register 
15 = &(8) Condition 
48(30) Invalid options, data set attributes, or processing conditions 
specified for TERMRPL request: . 
@ CNV processing 
e The specified RPL is asynchronous 
e Chained RPLs 
e Path processing 
e Shared resources (LSR/GSR) 
@ Load mode 
e Relative record data sct 
e Data set contains spanned records 
e User not in key 0 and supervisor state 
® End-of-volume in process (secondary allocation) 
52(34) The previous request was TERMRPL. 
64(40) There is insufficient storage available to dynamically add another 


string. Or, the maximum number of placcholders that may be 
allocated to the request has becn allocated, and a placeholder is not 


available. 

68(44) You attempted to use a type of processing (output or control 
interval processing) that was not specified when the data set was 
opened 

72(48) You made a keyed request for access to an entry-scquenced data 


set, or you issued a GETIX or PUTIX to an entry-sequenced or 
relative record data set. 


76{4C) You issued an addressed or control interval PUT to add to a 
key-sequenced data set, or you issucd a control interval PUT to a 
relative record data set. 


80(50) You issued an ERASE request in one of the following situations: 


¢ For access to an entry-sequenced data set. 
e For access to an cntry-sequenced data set via a path. 
¢ With control interval access. 


84( 54) You specified OPTCD = LOC in one of the following situations: 


@ Fora PUT request. 
© In a request parameter list in a chain of request parameter lists. 
© For UBF processing. 


Figure 8 (Part 3 of 7). Logical Error Reason Codes in the Feedback Area of the 
Request Parameter List 
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Reason Code 
(RPLERRCD) 

When Register 

15 = 8(8) Condition 


88(58) You issued a sequential GET request without having caused 
~ VSAM to be positioned for it, or you changed from addressed 
access to keyed access without causing VSAM to be positioned for 
keycd-sequential retrieval; there was no positioning established for 
sequential PUT insert for a relative record data set, or you 
attempted an illegal switch between forward and backward 


processing. 
92(5C) You issued a PUT for update or an ERASE without a previous 
GET for update, or a PUTIX without a previous GETIX. 
96(60) You attempted to change the prime key or key of reference while 
making an update. 


100(64) You attempted to change the length of a record while making an 
addressed update. 


104(68) The RPL options are either invalid or conflicting in one of the 
follawing ways: 


e SKP was spccified and either KEY was not specificd or BWD 
was specified. 


e BWD was specified for CNV processing. 
@ FWD and LRD were spccified. 
@ Neither ADR, CNV, nor KEY was specificd in the RPL. 


e BFRNO is invalid (less than | or greater than the number of 
buffers in the pool). 


e WRTBFR, MRKBFR, or SCHBEFR was issued, but either 
TRANSID was greater than 31 or the shared resource option 
was not specified. 


e ICI processing was specified, but a request other than a GET 
or a PUT was issued. 


e MRKBFR MARK= OUT or MARK=RLS was issued but 
the RPL did not have a data buffer associated with it. 


e The RPL specified WAITX, but the ACB did not specify LSR 
or GSR. 


Figure 8 (Part 4 of 7). Logical Error Reason Codes in the peedback Area of the 
Request Parameter List 
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Reason Code 
(RPLERRCD) 

When Register 

15 = &(8) Condition 


108(6C) RECLEN specified was larger than the maximum allowed, equal to 
0, or smaller than the sum of the length and the displacement of 
the key ficld; RECLEN was not equal to record (slot) size specified 
for a relative record data sct. The automatic increase in the record 
size of an upgrade index for the base cluster may cause an incorrect 
RECLEN specification. 


112(70) KEYLEN specified was too large or equal to 0. 


116(74) During initial data set loading (that is, when records are being 
stored in the data set the first time it’s opened), GET, POINT, 
ERASE, direct PUT, skip-sequential PUT, or PUT with 
OPTCD= UPD is not allowed. For initial loading of a relative 
record data sct, the request was other than a PUT insert. 


120(78) The request was operating under an incorrect TCB. For example, 
an end-of-volume call or a GETMAIN would have been necessary 
to complete the request, but the request was issucd from a job step 
other than the one that opencd the data set. The request can be 
resubmitted from the correct task, if the new request reestablishes 
positioning. 


124(7C) A request was cancelled for a user JRNAD exit. 
132(84) An attempt was made in locate mode to retrieve a spanned record. 


136(88) You attempted an addressed GET of a spanned record in a 
key-sequenced data set. 


140(8C) The spanned record segment update number is inconsistent. 


144(90) Invalid pointer (no associated base record) in an alternate index. 

148(94) The maximum number of pointers in the alternate index has been 
exceeded. 

152(98) Not enough buffers are available to process your request (shared 


resources only). 


156(9C) An invalid control interval was detected during keyed processing, or 
an addressed GET UPD request failed because the control interval 
flag was on, or an invalid control interval or index record was 
detected. The RPL contains the invalid contro! interval’s RBA. 


Figure 8 (Part 5 of 7). Logical Error Reason Codes in the Feedback Area of the 
Request Parameter List 
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Reason Code 

(RPLERRCD) 

When Register 

15 = 8(8) Condition 

160(A0) One or more candidates were found that have a modified buffer 
marked to be written. The buffer was left in write status with valid 
contents. With this condition, it is possible to have other buffers 
invalidated or found under exclusive control. 


164{A4) One of the following invalid options was specified for a 
CNVTAD/MNTACQ/ACQRANGE request: 


@ Generic key (GEN) 

e Load mode 

e Path processing 

© User buffers (UBF) with LSR/GSR 

e Key-sequenced data set, but not key processing (KEY) 

e Entry-sequenced data sct, but not address processing (ADR) 
e Relative record data sct, but not key processing (KEY) 

¢ RPL is chained 

e Key-sequenced data sct has single-level imbedded index . 


168(A8) One of the following user parameter list errors was detected for 
CNVTAD/MNTACQ/ACQRANGE request: 


e No user parameter list is specified (RPLARG = 0) 
e Argument count is zero for CNVTAD/MNTACQ request 


e Ending argument is less than starting argument for 
ACQRANGE request 


e Parameter list not on word boundary 


i72(AC) ACQUIRE error returned by SVC 126 for 
MNTACQ/ACQRANGE request. 


176(BO0) _ Staging failure for MNTACQ/ACQRANGE request. 


180(B4) RBA/volume crror for MNTACQ/ACQRANGE request. . 
. (Required volume not mounted or specificd RBA(s) not on 
mounted volume.) 


Figure 8 (Part 6 of 7). Logical Error Reason Codes in the Feedback Area of the 
Request Parameter List 
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Reason Code 


(RPLERRCD) 

When Register 

15 = &(8) Condition 

184(B8) Catalog errors returned from SVC 126 for CNVTAD request. 

188(BC) Storage for ACQUIRE ECBs (subpool 241) is not available. 

192(C0) Invalid relative record number. 

196(C4) You issued an addressed request to a relative record data set. 

200(C8) You attempted addressed or control interval access through a path. 

204(CC) PUT insert requests are not allowed in backward mode. 

208(D0) The user has issued an ENDREQ macro instruction against an 
RPL that has an outstanding WAIT against the ECB associated 
with the RPL. This can occur when an ENDREQ 1s issucd from a 
STAE or ESTAE routine routine against an RPL that was started 
before the abend. No ENDREQ processing has been done. 

212(D4) During control area split processing, a condition exists that prevents 
the split of the index record. Index control interval size may need 
to be increased. | 

224(E0) MRKBER OUT was issued for a buffer with invalid contents. 

228(E4) Caller in cross-memory mode is not in supervisor state or RPL of 

- caller in SRB or cross-memory mode does not specify SYN 

processing. 

232(E8) UPAD error; ECB was not posted by user in cross-memory mode. 

236(EC) ‘Validity check error for SHAREOPTIONS 3 or 4. 

240(F0) For shared resources, one of the following is being performed: (a) 
an attempt is being made to obtain a buffer in exclusive control, (b) 
a buffer is being invalidated, or (c) the buffer use chain is changing. 
For more detailed feedback, reissue the request. 

244(F4) Register 14 stack size is not large enough. 

248(F8) Register 14 rcturn offset went negative. 

252(FC) Record mode processing is not allowed for a lincar data set. 

253(FD) VERIFY is not a valid function for a linear data set. 


Figure 8 (Part 7 of 7). Logical Error Reason Codes in the Feedback Area of the 


Request Parameter List 
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When the search argument you supply for a POINT or GET request is greater 
_ than the highest key in the data set, the reason code in the feedback area depends 
on the RPL’s OPTCD values, as shown in the table below: 


Request RPLsOPTCD Reason Code (RPLERRCD) 
Type Options When Register 15 = 8(8) 
Decimal Hexadecimal 


POINT GEN,KEQ 16 X"10' 
POINT GEN,KGE 4 x"4' 
POINT  FKS,KEQ 16 X"10" 
POINT  FKS,KGE 4 x'4' 
GET GEN,KEQ,DIR = 16 X"10" 
GET GEN,KGE,DIR 16 X"10' 
GET FKS,KEQ,DIR 16 X"10' 
GET FKS,KGE,DIR 16 X"10' 
GET GEN,KEQ,SKP 16 X"10' 
GET GEN,KGE,SKP 4 xX"4' 
GET FKS,KEQ,SKP 16 X"10' 
GET FKS,KGE,SKP 4 x"4' 


Positioning, Following Logical Errors. 
VSAM is unable to maintain positioning after every logical error. Whenever 
positioning is not maintained following an error request, you must reestablish it 


before processing resumes. 


Positioning may be in one of four states following a POINT or a direct request 
that encountered a logical error: 


Yes VSAM is positioned at the position in effect before the request in error 
was issued. 


No VSAM is not positioned, because no positioning was established at the 
time the request in error was issued. ~ 


New VSAM is positioned at a new position. 

U VSAM is positioned at an unpredictable position. 

The following table shows which positioning state applies to each reason code 
listed for sequential, direct, and skip-sequential processing. ''N/A" indicates that 


the reason code is not applicable to the type of processing indicated. Figure 9 on 
page 25 lists these codes and their meanings. 
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Reason Code 


(RPLERRCD) 

When Register 

15 = 8(8) 3 
Decimal Hexadecimal Sequential Direct Skip-Sequential 
4 x'4' Yes N/A Yes 
8 x's"! Yes No New 
12 x'Cc' Yes N/A Yes 
16 X'10' No No No 
20 X'14" . U No? No? 
24 X'18' Yes No No 
28 X'1C' Yes No Yes 
32 X‘'20' No No N/A 
36 X'24' Yes No New 
40 xX‘'28' Yes No No 
44 x" 2C¢" Yes New Yes 
64 X'40' No | No No 
68 x'44' Yes Yes Yes 
72 x" 48' Yes Yes Yes 
76 X'4C' Yes Yes Yes 
80 x'50' Yes Yes Yes 
84 x'54' Yes Yes Yes 
88 x" 58" Yes Yes Yes 
92 xX'Sc' Yes Yes Yes 
96 x"60' Yes Yes Yes 
100 x'64' Yes Yes Yes 
104 X'68' Yes New Yes 
108 x'6c' Yes New Yes 
112 x'70' Yes Yes Yes 
116 x'74' Yes Yes Yes 
120 xX'78' Yes No No 
124 x" IC" No No No 
132 X'84' Yes New Yes 
136 x '8s' No No N/A 
140 X'8c' Yes New Yes 
144 X"90' Yes Yes = Yes 
148 xX'94' Yes Yes Yes 
152 x'98' Yes No No 
156 x'9c' Yes No No 
160 X'AO' N/A No N/A 
192 x'co' Yes Yes Yes 
196 x'c4' Yes Yes Yes 


Figure 9 (Part I of 2). Positioning Statcs of Reason Codes Listed for Sequential, 
Direct, and Skip-Sequential Processing 
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Reason Code 


(RPLERRCD) 
When Register 

15-8(8) 

Decimal Hexadecimal Sequential Direet Skip-Scquential 
200 x'cs' Yes Yes Yes 
204 x" cc" Yes Yes Yes 
208 X'pDo' Yes Yes Yes 
224 X EO N/A No N/A 
[i 5.25 
236 X'EC' No No No 
240 X'FO' Yes Yes Yes 


! A subsequent GET SEQ will retrieve the duplicate record; however, a 
subsequent GET SKP for the same key will get a sequence crror. Ina 
relative record data sct, a subsequent PUT SEQ positions to the next slot 
(whether the slot is empty or not). 


2 PUT UPD, DIR or UPD, SKP retains positioning. The RPL contains an 
’ RBA that could not be obtained for exclusive control. 


Figure 9 (Part 2 of 2) Positioning States of Reason Cades Listed for Sequential, 
Direct, and Skip-Sequential Processing 





Reason Code (Physical Errors) 


If a physical error occurs and you have no SYNAD routine (or the SYNAD exit 
is inactive), VSAM returns control to your program following the last executed 
instruction. The return code in register 15 indicates a physical error (12), and the 
feedback area in the request parameter list contains a reason code identifying the 
error; the RPL message area contains more details about the error. Register | 
points to the request parameter list. The RBA ficld in the request paramcter list 
gives the relative byte address of the control interval in which the physical error 
occurred. Figure 10 gives the reason codes in the feedback area and explains 
what each indicates. 
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Reason Code 


(RPLERRCD) 

When Register 

15=12(0C) Condition 

4(4) Read error occurred for a data set. 
8(8) ‘Read error occurred for an index set. 
12(C) Read error occurred for a sequence set. 
16(10) White error occurred for a data set. 
20(14) White error occurred for an index set. 
24(18) Write error occurred for a sequence sct. 


Figure 10. Physical Error Reason Codes in the Feedback Area of the Request 
Parameter List 


Figure 11 gives the format of a physical error message. The format and some of 
the contents of the message are purposely similar to the format and contents of 
the SYNADAF message, which is described in Data Administration: Macro 
Instruction Reference. 


Field Bytes Length Discussion 
Message 0-1 2 Binary value of 128 
Length 
2-3 2 Unused (0) 
Message 4-5 2 Binary value of 124 
Length - 4 . (provided for compatibility 
with SYNADAF Message) 
6-7 2 Unused (0) 
Address of 8-11 4 The I/O buffer associated 


1/O Buffer with the data whcre 
the error occurred 


The rest of the message is in printable format 


Date 12-16 5 YYDDD (year and day) 
17 l Comma (,) 
Time 18-25 8 HHMMSSTH (hour, minute, 
second, and tenths and 
hundredths of a second 


Figure 11 (Part 1 of 4). Physical Error Message Format 
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Field 


RBA 


Component 
TYPE 


Volume Serial 
Number 


Job Name 


Step Name 


Unit 


Device Type 


ddname 


Bytes 
26 
27-34 


35 
36-41 
42 
43-48 


49 


50-57 


58 
59-66 


67 
68-70 


71 
72-73 


74 
75-82 


83 


Length 


l 


Discussion 

Comma (,) 

Relative byte address of the 
record where 

the error occurred 

Comma (,) 

"DATA" or "INDEX" 
Comma (,) 

Volume serial number of the 
volume where 

the error occurred 


Comma (,) 


Name of the job where 
error occurred 


Comma (,) 


Name of the job step in 
which error occurred 


Comma (,) 


The unit, CUU (channel and 
unit), where 
the error occurred 


Comma (,) 


The type of device where 
the error 

occurred (always DA for 
direct access) 


Comma (,) 

The ddname of the DD 
statement defining the data 
set wherc the 

error occurred 


Comma (,) 


Figure {1 (Part 2 of 4). Physical Error Message Format 
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Field Bytes Length Discussion 


Channel 84-89 6 The channél command that 
caused the error in the first 
two bytes, followed by "_ OP" 


90 l Comma (,) 
Message 91-105 15 Messages are divided 
according to ECB condition 
codes: 


X'41" "INCORR LENGTH" 
“UNIT EXCEPTION" 
“PROGRAM CHECK" 
“PROTECTION CHK" 
“CHAN DATA CHK" 
"CHAN CTRL CHK" 
“INTFCE CTRL CHK" 
“CHAINING CHK" 
“UNIT CHECK" 


If the type of unit check can 

be determined, the ‘UNIT CHECK’ 
message is replaced by one of 

by one of the following: 


"CMD REJECT" 
“INT REQ" 
"BUS OUT CK" 
"EQP CHECK" 
"DATA CHECK" 
“OVER RUN" © 
“TRACK COND CK” 
"SEEK CHECK" 
“COUNT DATA CHK" 
"TRACK OVERRUN" 
“CYLINDER END" 
“NO RECORD FOUND" 
“FILE PROTECT" 
“MISSING A.M." 
-"OVERFL INCP" 


X‘'48' "PURGED REQUEST" 

X'4A' "I/O PREVENTED" 

X'4F' "R.HA.RO. ERROR" 
For any other ECB condition code: 


“UNKNOWN COND." 


Figure 11 (Part 3 of 4). Physical Error Message Format 
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Field Bytes Length Discussion 
106 1 Comma (,) 
Physical 107-120 14 BBCCHHR (bin, cylinder, 
Direct Access head, and record) 
Address 
121 1 Comma (,) 
Access 122-127 6 "VSAM" 
Method 


Figure 11 (Part 4 of 4). Physical Error Message Format 


‘Return Codes from Macros Used to Share Resources among Data Sets 


VSAM has a set of macros that enables you to share I/O buffers, I/O related 
control blocks, and channel programs among VSAM data sets. 


{| Return Codes from BLDVRP 


VSAM returns a code in register 15 that indicates whether the BLDVRP request 
was successful: 


Return 
Code 


0(0) 


| 4(4) 


8(8) 


12(C) 


16( 10) 


20(14) 
24( 18) 
28(1C) 


Condition 
VSAM completed the request. 


The requested data resource pool or index resource pool already exists 
in the address space (LSR) or in the system protect key (GSR). 


There is not enough virtual storage space to satisfy the request. 
GETMAIN or ESTAE failed. 


Buffers cannot be fixed in real storage. PAGEFIX failed. 


TYPE=GSR is specified but the program that issued BLDVRP is 


not in supervisor state with protection key 0 to 7. 


STRNO is less than 1 or greater than 255. 


BUFFERS is specified incorrectly. A size or number is invalid. 


_ The requested resource pool is invalid. A SHRPOOL value greater 


than 15 was specified. 
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32(20) 


36(24) 


Return Codes from DLVRP 


The resource pool already exists above 16 megabytes and the request 
was for storage below 16 megabytes, or the resource pool already 
exists below 16 megabytes and the request was for storage above 16 
megabytes. 


BLDVRP was issued to build an index resource pool but the required 
corresponding data resource pool does not.exist. 


VSAM returns a code in register 15 that indicates whether the DLVRP request 
was successful: 


Return 
Code 


0(0) 
a) 
8(8) 
12(C) 


16(10) 


Condition 
VSAM completed the request. 
There is no resource pool to delete. 


Thcre is not cnough virtual storage space to satisfy the requcst. 
GETMAIN or ESTAE failed. 


There is at least onc open data sct using the resource pool. 


TYPE=GSR is specified, but the program that issued DLVRP is not 
in supervisor state with protection key 0 to 7. 


Return Codes from End-of-Volume 


End-of-volume retums the following codes in register 15: 


Return 
Code 


0(0) 
4(4) 
8(8) 
12(C) 
16(10) 


Condition — 

Successful. 

The requested volume could not be mounted. 

The requested amount of space could not be allocated. 

I/O operations were in progress when end-of-volume was requested. 


The catalog could not be updated. 
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Chapter 2. VSAM Macro Formats and Examples 


This chapter contains macro instruction formats and examples. 


The macros that work at assembly time allow you to specify subparameter values 
as absolute numeric expressions, character strings, codes, and expressions that 
generate valid relocatable A-type address constants. The macros that work at 
execution allow you also to specify these values as: 


e Register notation, where the expression designating a register from 2 through 
12 is enclosed in parentheses; for example, (2) and (REG), where REG is a 
label cquated to a numbcr from 2 through 12 


e An expression of the form (S,scon), where scon is an expression valid for an 
S-type address constant, including the base-displacement form 


e An expression of the form (*,scon), where scon is an expression valid for an 
S-type address constant, including the base-displacement form, and the 
address specified by scon is indirect—that is, it gives the location of the area 
that contains the value for the subparameter. 


For most programming applications, you can conveniently use register notation 
or absolute numeric expressions for numbers, character strings for names, and 
register notation or expressions that generate valid A-type address constants for 
addresses. Appendix C, “Operand Notation” on-page 181, gives ali the ways of 
coding each parameter for the macros that work at execution time. 


You can write a reentrant program only with execution-time macros. 
Appendix B, “List, Execute, and Generate Forms of Macros” on page 171, 
describes alternative ways of coding these macros for reentrant programs. This 
chapter describes the standard form of these macros. 
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ACB 


ACB Macro (Generate an Access Method Control Block at Assembly 
Time) 


The format of the ACB macro is: 


[AM = VSAM] 
[| ,BSTRNO = number] 
|, BUFND = nwnber| 
|,BUFNI = number} 
[| ,BUFSP = number] 
|, CATALOG = YES|NO] 
{,CRA=SCRA|UCRA] 
[|,DDNAME = ddname} 
[,EXLST = address] 
[ MACRF = ({ADR]f,CNV][, KEY] 
[,CFX|NFX] 
|. DDNIDSN] 
_LDFRINDE] 
[, DIR}, SEQU,SKP] 
LICUNCY 
LENJLOUT] 
LNISISISL 
|, NRM|AIX] 
[.NRS|RST| 
|, NSR|LSR|GSR] 
|, NUB|UBE)} 
[ .MAREA = address] 
|, MILEN = number| 
[,PASSWD = address} 
[L, RMODE31I = {ALL] BUFF|CB|NONE}| 
[ SHRPOOL = {0|2umber}| 
[,STRNO = number] 





Note: The RMODE31I parameter replaces the AMODE31 subparameter shown 
in previous releases. 


Values for ACB macro subparameters can be specified as absolute numeric 
expressions, character strings, codes, and expressions that generate valid 
relocatable A-type address constants. 


label 
is | to 8 characters that provide a symbolic address for the access method 
control block that is assembled and also, if you omit the DDNAME 
parameter, serves as the ddname. 


AM = VSAM 
. specifies that the access method using this control block is VSAM. 


BSTRNO = number 


specifies the number of strings initially allocated for access to the base 
cluster of a path. The default is STRNO. BSTRNO is ignored if the 
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object being opened is not a path. If the number specified for BSTRNO is 
insufficient, VSAM will dynamically extend the number of strings as needed 
for the access to the base cluster. BSTRNO can influence performance. 
The VSAM control blocks for the set of strings specified by BSTRNO are 
allocated on contiguous virtual storage, whereas this is not guaranteed for 
the strings allocated by dynamic extension. 


BUFND = number ; 
specifies the number of I/O buffers VSAM is to use for transmitting data 
between virtual and auxiliary storage. A buffer is the size of a control 
interval in the data component. The minimum number you may specify is 
1 plus the number specified for STRNO (if you omit STRNO, BUFND 
must be at Icast 2, because the default for STRNO is 1). The number can 
be supplied by way of the JCL DD AMP parameter as well as by way of 
the macro. The default is the minimum number required. Note, however, 
that minimum buffer specification does not provide optimum sequential 
processing performance. Generally, the more data buffers specificd, the 
better the performance. Note also that additional data buffers will benefit 
direct inserts or updates during control arca splits and will bencfit spanned 
record accessing. For more information, see “Optimizing Performance” in 
VSAM Administration Guide. 


BUFNI = number . 
specifies the number of I/O buffers VSAM is to use for transmitting the 
contents of index entries between virtual and auxiliary storage for keyed 
access. A buffer is the size of a control interval in the index. The 
minimum number is the number specified for STRNO (if you omit 
STRNO, BUFNI must be at least 1, because the default for STRNO is 1). 
You can supply the number by way of the JCL DD AMP parameter as 
well as by way of the macro. The default is the minimum numbcr 
required. . 


Additional index buffers will improve performance by providing for the 
residency of some or all of the high-level index, thereby minimizing the 
number of high-level index records to be retricved from DASD for 
key-direct processing. For more information, see “Optimizing 
Performance” in VSAM Administration Guide. 


BUFSP = number 

specifies the maximum number of bytes of virtual storage to be used for the 
data and index I/O buffers. VSAM gets the storage in your program’s 
address space. If you specify less than the amount of space that was 
specificd in the BUFFERSPACE parameter of the DEFINE command 
when the data set was defined, VSAM overrides your BUFSP spccification 
upward to the value specified in BUFFERSPACE. (BUF FERSPACE, by 
definition, is the least amount of virtual storage that will ever be provided 

- for I/O buffers.) You can supply BUFSP by way of the JCL DD AMP 
parameter as well as by way of the macro. If you don’t specify BUFSP in 
either place, the amount of storage used for buffer allocation is the /argest 
of: 


@ The amount specified in the catalog (BUFFERSPACE), 


e The amount determined from BUFND and BUFNI, or 
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e The minimum storage required to process the data set with its specified 
processing options. 


If BUFSP is specified and the amount is smaller than the minimum 
amount of storage required to process the data set, VSAM cannot open the 
data set. 


A valid BUFSP amount takes precedence over the amount called for by 
BUFND and BUFNI. [If the BUFSP amount is greater than the amount 
called for by BUFND and BUFNI, the extra space is allocated as follows: 


e When MACREF indicates direct access only, additional index buffers are 
allocated. 


e When MACRE indicates sequential access, one additional index buffer 
and as many data buffers as possible are allocated. 


If the BUFSP amount is less than the amount called for by BUFND and 
BUFNI, the number of data and index buffers 1s decreased as follows: 


e When MACREF indicates direct access only, the number of data buffers 
is decreased to not fewer than the minimum number. Then, if required, 
the number of index buffers is decreased until the amount called for by 
BUFND and BUFNI complies with the BUFSP amount. 


e When MACRE indicates sequential access, the number of index buffers 
is decreased to not fewer than | more than the minimum number. 
Then, if required, the number of data buffers is decreased to not fewer 
than the minimum number. [If still required, | more is subtracted from 
the number of index buffers. 


e Neither the number of data buffers nor the number of index buffers is 
decreased to fewer than the minimum number. 


If the index doesn’t exist or isn’t being opened, only BUFND, and not 
BUEFNI, enters into these calculations. The bufferspace must not exceed 
16776704. 


CATALOG = YES|NO 


specifies whether a catalog is being opened as a catalog (YES) or as a data 
set (NO). When NO is coded (or taken as the default), you can process the 
catalog with request macros (GET, PUT, ctc). Your program must be 
APF-authorized to process a catalog as a data set. To open a password 
protected catalog for processing with VSAM macros, you must supply its 
master password. When CATALOG = YES is coded, the catalog must be 
processed with an SVC designed for that purpose. (Access method services, 
for example, processes catalogs with SVC 26.) The request macros are 
invalid for processing a catalog “as a catalog.” VSAM users should alter the 
contents of a catalog only by access method services commands. 


CRA=SCRA|UCRA 


specifies that a catalog recovery area is to be opened and that the control 
blocks are to be built in either system storage (SCRA) or user storage 
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(UCRA). If you specify SCRA and issue record management requests, you 
must operate in key 0. If you specify UCRA, you must be authorized by 
the system and you must supply the master password of the master catalog. 


DDNAME = ddname 
is 1 to 8 characters that identify the data set that you want to process by 
specifying the JCL DD statement for the data set. You may omit 
DDNAME and provide it by way of the label or by way of the MODCB 
macro before opening the data sect. MODCB is described later in this 


chapter. 


EXLST = address 
specifies the address of a list of addresses of exit routines that you are 
providing. The list is established by the EXLST or GENCB macro. If you 
use the EXLST macro, you can specify its label here as the address of the 
exit list. If you use GENCB, you can specify the address returned by 
GENCB in register 1 or the label of an area you supplied to GENCB for 
the exit list. Omitting this parameter indicates that you have no exit 
routines. Exit routines are described in “User-Wnitten Exit Routines” in 
Data Facility Product: Customization. 


MACRF = (JADR]], CNV] ,KEY] 
[,CFXINFX] 
LDDNIDSN] 
|,DFRINDF] 

[, DIR}, SEQILSKP} 
LICHNCY 
LINJLOUT| 

[ NIS|SIS| 
L.NRM[AIX] 

|. NRSIRST] 

|, NSRILSR|GSR] 
{NUB|UBF) 


specifies the kind(s) of processing you will do with the data set. The 
subparameters must be meaningful for the data set. For example, if you 
specify keyed access for an entry-sequenced data set, you cannot open the 
data set. You must specify all the types of access you’re going to use, 
whether you use them concurrently or by switching from one to the other. 
Figure 12 on page 38 gives the subparameters;-each group of 
subparameters has a default value (indicated by underlining). You may 
specify subparameters in any order. You may specify both ADR and KEY 
to process a key-sequenced data set. You may specify both DIR and SEQ; 
with keyed access, you may specify SKP as well. If you specify OUT and 
want mercly to retrieve some records as well as update, delete, or insert 
others, you need not also specify IN. 


Note: The RMODE3! parameter replaces the AMODE31 subparameter 
shown in previous releases. 
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Option 
ADR 


NFX 
DDN 
DSN 


DFR 


Meaning 


Addressed access to a key-sequenced or an entry-sequenced data 
set; RBAs are used as search arguments and sequential access is by 
entry sequence. 


Access is to the entire contents of a control interval rather than to 
an individual data record. If the data sct is password protected, | 
you must supply the address of the control or higher-level 
password in the ACB PASSWD parameter. 


Keyed access to a kcy-sequenced or relative record data set; keys 
or relative record numbers are used as search arguments and 
sequential access is by key or relative record number. 


Control blocks and I/O buffers are to be fixed in real storage; 
MACRF = ICI must also be specified. 


Control blocks and I/O buffers are fixed in real storage only 
during I/O operations. 


Subtask shared control block connection is based on common 
ddnames. 


Subtask shared control block connection is based on common 
data sct flames. | 


With shared resources, writes for direct PUT requests are deferred 
until the WRTBFR macro is issued or until VSAM necds a buffer 
to satisfy a GET request; deferring writes saves I/O requests in 
cases where subsequent requests can be satisfied by the data 
already in the buffer pool. 


Writes are not to be deferred for direct PUTs. 


. Direct access to a key-sequenced, entry-sequenced, or a relative 


record data set. 


Sequential access to a key-sequenced, entry-sequenced, or a 
relative record data set. 


Skip-sequential access to a key-sequenced or a relative record data 
set; used only with keyed access in a forward direction. 


Processing is limited to improved control interval processing; 
access is faster because fewer processor instructions are executed. 


Processing other than improved control interval processing. 


Retrieval of records of a key-sequenced, entry-sequenced, or a 
relative record data set; (not allowcd for an empty data set). If the 
data sct is password protected, you must supply the address of the 
read or higher-level password in the ACB PASSWD parameter. 


Figure 12 (Part | of 2). MACRF Options 
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Option 
OUT 


NIS 
SIS 


NRM 
AIX 


NRS 
RST 


NSR 


GSR 


NUB 
UBF 


Meaning 


Storage of new records in a key-sequenced, entry-sequenced, or 
relative record data set (not allowed with addressed access to a 
key-sequenced data set); update of records in a kcy-sequenced, 
entry-sequenced, or relative record data set; deletion of records from a 
key-sequenced data sct or relative record data set. 


If the data sct is password protected, you must supply the address of 
the update or higher-level password in the ACB PASSWD parameter. 


Normal insert strategy. 


Sequential insert strategy (split control intervals and control areas at 
the insert point rather than at the midpoint when doing direct PUTs); 
although positioning is lost and writes are done after each direct PUT 
request, SIS allows more efficient space usage when direct inserts are 
clustered around certain keys. 


The object to be processed is the one namcd in the specified ddname. 


The object to be processed is the alternate index of the path specified 
by ddname, rather than the base cluster via the alternate index. 


Data set is not reusable. 


Data set is reusable (high-used RBA is reset to 0 during OPEN). If 
the data set is password protected, you must supply the address of the 
update or higher-level password in the ACB PASSWORD paramcter. 


Nonshared resources. 


Local shared resources. Each address space may have up to 16 index 
resource pools and 16 data rcsource pools independent of other 
address spaces. Unless you are using the default, SYRPOOL=0, you 
must specify the SHRPOOL parameter to indicate which resource 
pool you are using. Specifying LSR will cause a data set to use the 
local resource pool built by the BLDVRP macro. If an index 
resource pool exists at the time an OPEN macro 1s issued, the index 
for a key-sequenced data set will be connected to the index resource 


pool. 


Global shared resources; all address spaces may have local and ylobal 
resources pools, where tasks in an address space with a local resource 
pool may usc either the local resource pool or the global resource 


pool. 
Management of I/O buffers is left up to- VSAM. 


Management of I/O buffers is Icft up to the user; the work area 
specified by the RPL (or GENCB) AREA parameter is, in effect, the 
1/O buffer—VSAM transmits the contents of a control interval directly 
between the work area and direct access storage; valid when 
OPTCD= MVE and MACRF= CNV are specified; when ICI is 
specified, UBF is assumed. 


Figure 12 (Part 2 of 2). MACRF Options 
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MAREA = address 
specifies the address of an optional OPEN/CLOSE or TYPE=T option 
(CLOSE macro) message area. See “OPEN/CLOSE Message Area for 
Multiple Reason or Warning Messages” on page 7 for more information. 


MLEN = number , : 
specifies the length of an optional OPEN/CLOSE or TYPE=T option 
(CLOSE macro) message area. Default = 0; maximum =32K. See 
“OPEN/CLOSE Message Area for Multiple Reason or Warning Messages” 
on page 7 for more information. 


PASSWD = address 
specifies the address of a field that contains the highest-level password 
required for the type(s) of access indicated by the MACRF parameter. The 
first byte of the field pointed to contains the length (in binary) of the 
password (maximum of 8 bytes). Zero indicates that no password is 
supplied. If the data set is password protected and you don’t supply a 
required password in the access method control block, VSAM will give the 
console operator the opportunity to supply it when you open the data sct. 


RMODE31I = [ALL|BUFF|CB|NONE| 
specifics where VSAM OPEN is to obtain virtual storage (above or below 
16 megabytes) for control blocks and I/O buffers. 


The values specified by the RMODE31 parameter only have an effect on 
VSAM at the setting just before an OPEN is issued. At all other times, 
changing these values has no effect on the residency of the control blocks 
and I/O buffers. 


ALL 
both VSAM control blocks and I/O buffers are to be obtained above 
16 megabytes. 


BUFF 
only VSAM I/O buffers are to be obtained above 16 megabytes. 


CB 
only VSAM control blocks are to be obtained above 16 megabytes. 


NONE 
both I/O buffers and VSAM control blocks are to be built below 16 
megabytes. This is the default. 


Note: In previous releases, the MACRF subparameter AMODE31 
specified that I/O buffers were to be obtained above 16 megabytes and that 
the caller was running in 31-bit addressing mode. The RMODE31 
parameter replaces the AMODE31 subparameter and the two are mutually 
exclusive. If both the AMODE31 subparameter and the RMODE31 
parameter are specified within the same program, AMODE31 is ignored. 


SHRPOOL = {nwmber|0} 
identifies which LSR pool is to be connected to the ACB. This parameter 
is valid only when MACRF = LSR is also specified. The identification 
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number of the shared pool must be a number from 0 to 15. The default is 
0. 


STRNO = number 
specifies the number of requests requiring concurrent data set positioning 
VSAM is to be prepared to handle. The default is 1. A request is defined 
by a given request parameter list or chain of request parameter lists. See 
“RPL Macro (Generate a Request Parameter List at Assembly Time)” on 
page 126 and “GENCB Macro (Gencrate a Request Parameter List at 
Exccution Timc)” on page 80 for information on request paramctcr lists. 
When records are loaded into an empty data set, the STRNO value in the 
access method control block must be 1. 


VSAM dynamically extends the number of strings as they are needed by 
concurrent requests for this ACB. This automatic extension can influence 
performance. The VSAM control blocks for the set of strings specified by 
STRNO are allocated on contiguous virtual storage, but this is not 
guaranteed for the strings allocated by dynamic extension. Dynamic string 
addition cannot be done when using the following options: 


e Load mode 
® ICl 
e LSR or GSR 


For STRNO, you should specify the total number of request parameter 
lists or chains of request parameter lists that you are using to define 
requests. (VSAM needs to remember only one position for a chain of 
request parameter lists.) However, each position beyond the minimum 
number that VSAM needs to be able to remember requires additional 
virtual storage space for: 


¢ A minimum of one data 1/O buffer and, for keyed access, one index 
J/O buffer (the size of an I/O buffer is the control interval size of a data 
set) 


e Internal control blocks and other areas 
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Example 1: ACB Macro 


In this example, the ACB macro is used to identify a data set to be opened and 
to specify the types of processing to be performed. The access method control 
block generated by this example is built when the program is assembled. 


BLOCK ACB - AM=VSAM, BUFND=4, BLOCK gives symbolic 


BUFNI=3, address of the access 
BUFSP=19456, method control block. 
DDNAME=DATASETS, 
EXLST=EXITS, 
MACRF=(KEY, DIR,SEQ, OUT), 
PASSWD=FIELD, 
STRNO=2 

FIELD DC FL1'6',C'CHANGE’ The update password: 


CHANGE has 6 characters. 


The ACB macro’s parameters are: 


BUFND specifies four I/O buffers for data; BUFNI specifies three I/O 
buffers for index entrics;.and BUFSP specifics 19456 bytes of buffer space, 
enough space to accommodate control intervals of data that are 4096 bytes 
and control intervals of index entries that are 1024 bytes. 


DDNAME specifies that this access method control block is associated with 
a DD statement named DATASETS. 


EXLST specifies that the exit list associated with this access method control 
block is named EXITS. 


MACRF specifies keyed-direct and keyced-sequential processing for both 
insertion and update. 


PASSWD specifies the location, FIELD, of the password provided. FIELD 
contains the length of the password as well as the password itself. 


STRNO spccifies that two requests will require concurrent positioning. 
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Example 2: ACB Macro 


ACB 


In this example, the ACB macro is used to identify a data sct to be opened and 
to specify the types of processing to be performed. An LSR pool is connected to 
the data set. The access method control block generated by this example is built 
when the program is assembled. The caller requests that the VSAM control 
blocks and I/O buffers be obtained above 16 megabytes if possible. | 


BLOCK2 ACB AM=VSAM, BLOCK2 gives symbolic 
DDNAME=DATASETS, address of the access 
EXLST=EXITS, method control block. 
MACRF=(KEY,DIR, 
LSR, SEQ, OUT), 
PASSWD=FIELD, 
RMODE31=ALL, 
SHRPOOL=1 


FIELD DC FL1'6',C'CHANGE' The update password: 
CHANGE has 6 characters. 


The ACB macro’s parameters are: 


e¢ DDNAME spccifics that this access method control block is associated with 
a DD statement named DATASETS. 


@ EXLST specifies that the exit list associated with this access mcthod control 
block is named EXITS. 


@ MACRF specifies keyed-direct and keyed-sequential processing for both 
insertion and update. LSR indicates that the LSR pool created by BLDVRP 
is to be connectcd to the data set. 


e PASSWD specifies the location, FIELD, of the password provided. FIELD 
contains the length of the password as well as the password itsclf. 


® RMODE31=ALL specifies that you want both VSAM control blocks and 
I/O buffers to reside above 16 megabytes. 


e SHRPOOL specifies that the LSR pool with the identification number of 1 is 
to be used. However, if an index resource pool exists at the tume the OPEN 
macro is issued, the index for the key-sequenced data sct will be connected to 
the index resource pool. 
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ACQRANGE Macro (Stage Data) 
The format of the ACQRANGE macro is: 


[/abeff ACQRANGE | RPL= address 


RPL = address . 
specifies the address of the RPL that identifies your open data sct and your 
argument range. RPL parameters that have mcaning for ACQRANGE are 
as follows: 


ACB= address 
identifies your VSAM data set. 


ARG = address 
identifies your starting and ending arguments. Address points to a 
parameter list, aligned on a fullword boundary as follows: 
KEY-SEQUENCED DATA SET 
Offset Length Contents 


0 4 Feedback area: Address 
of an ECB WAIT list 


4 K Starting full argument 
(K = key length) 


4+K K (K = key length) 


ENTRY-SEQUENCED DATA SET OR RELATIVE RECORD 
DATA SET 


Offset Length Contents 


0 4 Feedback area: Address 
of an ECB WAIT list 

4 4 Starting RBA/RRN 

8 4 Ending RBA/RRN 


The maximum number of argument pairs you may specify is one. 


OPTCD = ({ADR|KEY} 
,{ASYISYN} 
{KEQ|KGE} 
»FKS) 


ADR is valid for an entry-sequenced data set, error for key-sequenced. 
data set or relative record data set. 
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KEY is valid for key-sequenced data set and relative record data set, 
error for entry-sequenced data set. 


If ASY is specified, you cannot WAIT on the RPLECB field for 
MNTACQ or ACQRANGE. You use the address placed in the 
parameter list feedback area. This address points to a list of event 
control blocks (ECB) (in standard WAIT list format) which you may 
use in place of the RPLECB field. 


GEN is not supported; if specified, it will give an error indication. 


All other OPTCD subparameters are not applicable, and, if specified, 
are ignored with no error indication. 


Because your request may result in the staging of numcrous cylindcrs, a single 
ECB is not sufficient for an asynchronous ACQRANGE request. The RPLECB 
field is inoperative for the ACQRANGE interface. Upon rcturn from an 
asynchronous ACQRANGE, the feedback area of the ACQRANGE parameter 
contains the address of a standard ECB WAIT list. You must then use this list 
in conjunction with either the WAIT macro or the EVENTS macro of MVS. 
An asynchronous request must conclude with cither CHECK, ENDREQ, or 
CLOSE. The paramcter list cannot be reused until the CHECK, ENDREQ, or 
CLOSE is completed. 


At the conclusion of this macro, the RPL is disconnected. Any positioning in 


effect prior to exccution of ACQRANGE will be lost. You may have to 
reposition. Chained RPLs are not supported by this macro. 
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BLDVRP Macro (Build VSAM Resource Pool) 


The format of the BLDVRP macro is: 





BLDVRP | BUFFERS = (size(number),size(number),...) 
[, FIX = (BFRJIOB|(BFR,IOB)}] 

[ ,KEYLEN = length] 

|, RMODE31 = {ALL|BUFF|CB|NONE}| 
| SHRPOOL = {0[2umber}] 

|, MODE = (2431}] 

»TRNO = number 

|, TYPE = {LSR], DATA|INDEX] | GSR}] 










Note: The RMODE31 parameter replaces the LOC = BELOW|ANY parameter 
shown in previous releases. | 


The BLDVRP macro has a standard form and list and execute forms. The 
standard form builds a parameter list and passes control to VSAM to build the 
resource pool. The list and execute forms are described in Appendix B, “List, 
Exccutc, and Gencrate Forms of Macros” on page 171. 


BUFFERS = (size(number),size(number),...) 
specifies the size and number of buffers in each buffer pool in the resource 
pool. The number of buffer pools in the resource pool is implied by the 
number of size(number) pairs you specify. . 


Whcen you process a key-sequenced data set, the index component, as well 
as the data component, shares the buffers of a buffer pool. When you use 
an alternate index to process a base cluster, the components of the alternate 
index and the base cluster share buffers. The components of alternate 
indexes in an upgrade set share buffers. Buffers of the appropriate size and 
number must be provided for all these components. Each component uses 
the buffer pool with buffers either the required size or larger. 


size 
is 512, 1024, 2048, 4096, and then in increments of 4096 to a 
maximum of 32K bytes. 


number 
is at Icast 3. 


Size times number must be less than 16 megabytes. 


FIX = {BFR|IOB|(BFR,IOB)} 
specifies that I/O buffers (BFR), or I/O-related control blocks (IOB), or 
both, are to be fixed in real storage. With GSR, IOB includes channel 
programs. If the program that issues BLDVRP with FIX specified is not 
authorized to fix areas in real storage, FIX i§ ignored. A program is 
authonzed if it is in supervisor state with protection key 0 to 7, or has been 
link-edited with authorization (the authorized program facility is described 
in Supervisor Services and Macro Instructions). 
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Note: If FIX is specified, DLVRP must be issued by the same task that 
issues BLDVRP. 


KEYLEN = length 
specifies the maximum key length of the data sets that are to share the 
resource pool. The default is 255. The keys whose lengths must be 
provided for are the prime key of each key-sequenced data set and the 
alternate key of each alternate index that is used for processing or is being 
upgraded. If nonce of the data scts is keyed, specify 0. 


RMODE31 = {ALL|BUFF|CB|NONE} 
specifies the storage residence location of the buffers and I/O related control 
blocks of the LSR pool identificd with the SHIRPOOL keyword. 


The RMODE31 parameter tells the VSAM OPEN routines where to 
obtain storage for the I/O related control blocks and I/O buffers. 
Therefore, the only time the values specified by the RMODE3! parameter 
have any effect on VSAM is on the setting just before an OPEN is issued. 
At other times, changing these values has no effect on the residency of the- 
1/O related control blocks and I/O buffers. 


Note: ‘The RMODE3]1 paramcter is valid only when TYPE = LSR is 
specified. 


ALL 
both 1/O buffers and the VSAM I/O related control blocks associated 
with the pool are to reside above 16 megabytes. 


BUFF 
specifics that only I/O buffers are to reside above 16 megabytes. 


CB 
@niy the VSAM {/O related control biocks associated with the pool 
4 are to reside above 16 megabytes. 


NONE 
both I/O buffers and the VSAM I/O related control blocks associated 
with the pool are to reside below 16 megabytes. This is the default. 


Note: In previous releases, the LOC = (BELOW|ANY) parameter was 
uscd to specify that buffers in the pool be created above 16 mcgabytcs. The 
RMODE31 parameter replaces the LOC paramcetcr and the two paramcters 
are mutually exclusive. If both are specificd on the BLDVRP macro, the 
LOC parameter is ignored. 


SHRPOOL = {0|nuwmber} | 
specifies the identification number of a shared resource pool. Valid only 
when TYPE = LSR is also specified or defaulted. This parameter also 
requires that the RMODE31 parameter be specified. 


0 
specifies the shared pool with the ID of 0. It is the default LSR pool. . 
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number 
specifies the shared pool with the ID of munber where number can be 
0 to 15. The LSR control block and buffer pool residence is 
determined by the RMODE31 = keyword. 


MODE = {24[31} 
specifies the format of the BLDVRP parameter list that is to be generated. 


24 
specifies that a standard form (24-bit) parameter list address be 
generated. This is the default. 


31 
specifies that a long form (31-bit) parameter list address be generated. 
This value must be coded if the parameter list resides above 16 
megabytes. 


STRNO = number 
specifies the total number of placcholders required for all the data sets that 
are to share the resource pool. | is minimum; 255 is maximum. 


The number should cqual the potential number of requests that may be 

. issued concurrently for all the data sets that will share the resource pool. Ifa 
request fails because the number of placeholders is insufficient (you receive a 
reason code of 64 (X’40’) in the RPL feedback area), you may retry the 
request; it will be assigned a placcholder if one has been released. See 
Figure 8 on page 17 for a complcte description of reason code 64 (X’40’). 


TYPE = {LSR[,DATA|INDEX] | GSR} 
specifies whether a local (LSR) or a global (GSR) resource pool is to be 
built. 


LSR 
specifies that the caller requests a local shared resource pool. A 
maximum of 16 data and 16 index resource pools can be built in one 
address space. Each resource pool must be built individually. 


. DATA 
specifies that the caller wants to build a data resource pool. This 
option requires that LSR be specified. This resource pool must exist 
before an index pool with the same shared pool ID can be built. 


INDEX 
specifies that the caller wants to build an index resource pool. This 
option requires that LSR be specified or defaulted. INDEX must be 
specified in order to create a separate index resource pool. If it is not 
specified, both data and index componcnts will use the data pools. A 
data pool must already exist before an index pool with the same 
shared pool ID can be built. 


GSR 
specifies that the caller requests a global shared resource pool. 
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Only one BLDVRP TYPE= GSR may be issued for the system for each of 
the protection keys 0 through 7. The program that issues BLDVRP 
TYPE=GSR must be in supervisor state with protection key 0 to 7. 


| Example 1. Obtaining an LSR Pool above 16 Megabytes 


This example shows how both a local shared resource pool and a BLDVRP 
paramctcr list residing above 16 megabytes are obtaincd. 


POOL1 BLDVRP BUFFERS=(1024(5)), 
STRNO=4 


TYPE=LSR, 
MODE=31, 
RMODE31=ALL 


The BLDVRP parameters are: 


BUFFERS specifies that there is one buffer pool in the resource pool. This 
buffer pool contains 5 buffers, and each of these buffers is 1024 bytes. 


STRNO spccifies that 4 placcholders are required for the data sets to share 
the resource pool. 


TYPE specifics that a local resource pool is to be built. 


MODE specifies that a parameter list 1s to be generated that may reside 
above or below 16 megabytes. The value of 31 must be coded if the 
parameter list resides above 16 megabytes. 


RMODE31 specifies the location in storage for the I/O buffers and I/O 
related control blocks of the LSR pool. 


To connect the LSR pool to the data set, you must code the LSR and | 
SH/RPOOL parameters on the ACB. See “ACB Macro (Generate an Access 
Method Control Bloc’: at Assembly Time)” on page 34. 
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| Example 2. Request for Separate Data and Index Resource Pools 
| This example shows how the two separate data and index resource pools with an 
| identification equal to 3 are created. 


POOL1 BLDVRP BUFFERS=(2048(4)), 
TYPE=(LSR, DATA), 


SHRPOOL=3, 
STRNO=2, 
- RMODE31=ALL 
LTR R1i5,R15 Check return code. 
BNZ ERROR Do not build index if 
n error. 


POOL2 BLDVRP BUFFERS=(1024(5)), 
TYPE=(LSR, INDEX), 
SHRPOOL=3, 
STRNO=2, 
RMODE31=ALL 


| Note: POOLI must be created first because the data pool must exist before the 
| index pool with the same shared pool ID can be built. Also, only one data and 
| one index pool can be built for a shared pool ID. 
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CHECK Macro (Wait for Completion of Request) 


The format of the CHECK macro is: 


[labeh | CHECK § {| RPL= address | 


where: 


label 
is 1 to 8 characters that provide a symbolic address for the CIHECK macro. 


RPL = address 
specifics the address of the request parameter list that defines the request. 
You may specify the address in register notation (using a register from 1 
through 12, enclosed in parentheses) or specify it with an expression that 
gencrates a valid relocatable A-type address constant. 


Examplc 1: Check Return Codes after an Asynchronous Request 
In this example, return codes are checked after an asynchronous request. The 


CHECK macro 1s used to cause an exit to be taken if there 1s a logical or 
physical error or if the end of the data sct is reached. 


REQPARMS RPL OPTCD=ASY 


GET  RPL=REQPARMS 


LTR 15,15 Was the request completed 
successfully? 
BNZ REJECTED Zero indicates the request was 


accepted. If it was not 
accepted, register 15 contains 
4&: REQPARMS is active for 
another request. Continue to 
work on something that is not 
dependent on the request. 


CHECK RPL=REQPARMS CHECK would cause one of the 
three exits to be taken if 
there was a logical or physical 
error or if the end of the 
data set was reached and an 
active exit list exists. 


LTR 15,15 Test return indication is 
register 15. 


BNZ FAILURE Zero indicates the request 
completed successfully. If 
it failed, register 15 
contains 8 or 12: there was 
a logical or a physical 
error. =f 


REJECTED ... 
FAILURE 
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Unless you provide exit routines that terminate processing, always test register 15 
after the CHECK. Ifa routine returns to VSAM, register 15 is reset and control 
is passed back to your program immediately after the CHIECK. An error analysis 
routine normally issues SHOWCB or TESTCB to examine the feedback field in 
the request parameter list, so that, when your processing program gets control 
back, it doesn’t have to analyze the errors—but it may‘alter its processing if there 
was an error. If you don’t provide an error analysis routine, your program can 
issue SEEIOWCB or TESTCB to analyze an error when it gets control back 
following the CHIECK. 


Example 2: Check Return Codes after a Synchronous Request 


With synchronous processing, you should test register 15 after the request 
because the request may not have been accepted (register 15 contains 4) or. 
because an crror might have occurred (8 or 12): 


GET RPL=REQPARMS 


LTR 15,15 Was the request completed 
successfully? 
BNZ #£REJFAIL If branch is not taken, was 


the request accepted and 
completed succesfully? 


REJFAIL 
Example 3: Overlap Processing 


In this example, the CIIECK macro is used to wait for completion of a request 
before continuing to other processing. Access is asynchronous. 


BLOCK ACB 
LIST RPL ACB=BLOCK, Asynchronous access. 
AREA=WORK, 
AREALEN=50, 
: OPTCD=ASY 


LOOP GET RPL=LIST 

LTR 15,15 

BNZ NOTACCEP 

Do other processing. 

CHECK RPL=LIST Suspends your processing to wait 
for completion of GET if 
necessary and to cause VSAM to 
indicate return codes. 

LTR 15,15 

BNZ ERROR 

Process the record. 


B LOOP 
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NOTACCEP ... Request wds not accepted. 
ERROR eas Request failed. 
WORK DS  CLS50 Work area. 


After issuing the requcst, make sure that VSAM accepted it before you go on to 
other processing. When you have done as much other processing as you can, 
issue the CHIECK macro. VSAM will not give you back control until the 
request is complete. If you don’t want to issue CHECK until you know the 
request is complete, use the ECB parameter of the RPL macro or the 
10=COMPLETE parameter of the TESTCB macro. After you issue the 
CHECK, VSAM immediately returns a code and takes an exit, if necessary. See 
“RPL Macro (Generate a Request Parameter List at Assembly Time)” on 

page 126 and “GENCB Macro (Gencrate a Request Parameter List at Execution 
Time)” on page 80 for information on the ECB parameter. 


Example 4: Suspend a Request for Many Records 


In this cxamplc, a CHECK macro is issucd for the first request parameter list in a 
chain of parameter lists. If an error occurred for one of the request parameter 
lists in the chain and you have supplied error analysis routines, VSAM takes a 
LERAD or SYNAD exit before it returns control to your program after the 
CHECK. 


FIRST RPL ACB=BLOCK, 
AREA=AREA1, 
AREALEN=50, 
NXTRPL=SECOND, 
OPTCD=ASY 
SECOND RPL ACB=BLOCK, 
AREA=AREA2, 
AREALEN=50, 
NXTRPL=THIRD, 
OPTCD=ASY 
THIRD RPL ACB=BLOCK, Last list does not indicate 
AREA=AREA3, a next list. 
AREALEN=50, 
OPTCD=ASY 


LOOP GET  RPL=FIRST Request gives the address of 
the first request parameter 
LTR 15,15 ~ list. 
BNZ NOTACCEP 
Do other processing. 
CHECK RPL=FIRST 
LTR 15,15 


BNZ ERROR 
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Process the three records retrieved by the GET. 


B LOOP 

NOTACCEP ... Request wasn't accepted. 

ERROR ee Display the feedback field 
(FIELDS=FDBK) of each request 
parameter list to find 
out which one had an error. 

AREA1 DS CL50 A single GET request causes VSAM 


to put a record in each of AREA1, 
AREA1, and AREA3. 
AREA2Z: ODS CLS50 


AREA3 DS CL50 


After the CHECK, register 15 is set to indicate the status of the request. A code 
of 0 indicatcs that no error was associated with any of the request parameter lists. 
Any other codc indicates that an error occurred for onc of the request paramcter 
lists. You should issue a SH}OWCB macro for each request parameter list in the 
chain to find out which onc had an crror. VSAM doesn’t process any of the 
request paramcter lists beyond the one with an crror. 
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CLOSE Macro (Disconnect Program and Data) 


The format of the CLOSE macro is: 


jlabe] =| CLOSE | (address|,(options)],...) 


|, MODE = (24/31)] 
| TYPE=T] 





where: 


label 
is 1 to 8 characters that provide a symbolic address for the CLOSE macro. 


address 
specifies the address of the access method control block or DCB for cach 
data sct to be closed. You may specify the address in register notation 
(using a register from 2 through 12—in parentheses) or specify it with an 
expression that generates a valid relocatable A-type address constant. If 
you specify only onc address with a register, you must enclose the 
expression identifying the register in two scts of parentheses: for example, 


CLOSE ((2)). 


options , 
are options paramcters for usc only in closing non-VSAM data sets. If any 
options are specified with the address of an access method control block, 
VSAM ignores them. 


Note: Because the CLOSE parameters are positional, include a comma for 
options (even if you don’t specify options) before a subsequent parameter. 


MODE = (24/31) 
specifics the format of the CLOSE parameter list that is to be built. 


24 
specifies that a standard form (24-bit) parameter list address be built. 
This parameter list must reside below 16 megabytes and contain the 
address of ACBs residing below 16 megabytes. The caller, however, 
may be above 16 megabytes. This is the default parameter list 
format. 


31 
specifies that a long form (31-bit) parameter list address be built. 
This list can reside above or bclow 16 megabytes. This value must be 
codcd if the paramcter list resides above 16 megabytes or contains the 
address of an VSAM/VTAM ACB residing above 16 megabytes. 


TYPE=T 
specifics that VSAM is to complete outstanding I/O operations and update 
the catalog, but not disconnect the program from the data. 


You can issue a temporary CLOSE macro to cause VSAM to complete 
outstanding I/O operations, put back into the catalog the updated 
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information that was brought into virtual storage when the data set was 
opened, and write records in the SMF data set if you are using SMF. A 
temporary CLOSE doesn’t disconnect the program from the data set, so 
your program can continue to process the data set without issuing an 
OPEN macro again. 


You must close and reopen a newly created VSAM data set before you can 
issue noncreate requests. A temporary close is not adequate for this 


purpose. 


Note: If you are sharing subtasks or if you have issued an asynchronous request 
for access to a data set, you must issue a CHECK or an ENDREQ on all RPLs 
before you issue a CLOSE or CLOSE TYPE=T; otherwise, concurrent data set 
I/O activity will cause unpredictable results during a close. 


| Example: CLOSE Macro 


‘This example shows how to close an ACB with a parameter list that may reside 
above 16 megabytes. 


BLOCK1 ACB ; 
| , RMODE31=ALL VSAM control blocks 
: and 1/0 buffers may 
: be above 16 megabytes 
OPEN BLOCK1, OPEN/CLOSE parameter 
MODE=31 list may reside above 


16 megabytes 


CLOSE BLOCK1, 
MODE=31, 
TYPE=T 


The CLOSE parameters are: 


e MODE =31 ts required if the OPEN/CLOSE parameter list resides above 16 
megabytes or if the ACB resides above 16 megabytes. 


e TYPE indicates a temporary CLOSE. This causes VSAM to complete 
outstanding I/O operations, put back into the catalog the updated 
information that was brought into virtual storage when the data sct was 
opened, and write records in the SMF data set if you are using SMF. 
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CNVTAD Macro (Convert Address) 
The format of the CNVTAD macro is: 


Jlabe4 CNVTAD | RPL= address 


RPL = address 
specifics the address of the requcst parameter list (RPL). The RPL 
identifics your opened VSAM data set and your arguments. The following 
RPL parameters and subparameters have meaning for the CNVTAD 
macro: 


ACB = address 
identifics your VSAM data set. 


ARG = address 
identifics your arguments. The address points to a parameter list, 
aligned on a fullword boundary as follows: 


Key-scquenced data set 


Offset Length Contents 

0 3 Reserved; unused 

3 1 Number of arguments (N) 
(N = 1 to 255) 

4+(N-1)(10+ K) 4 Feedback RBA 


(K = key Icngth) 


8+ (N-1)(10+ K) 4 Feedback volume scrial number 
(K = key Icngth) 


14+ (N-1)(10+ K) K Full key argument 
(K = key length) 


Entry-sequenced data set or relative record data set 


Offset Length Contents 

0 3 Reserved; unused 

3 l Number of arguments (N) 

4+ (N-1)(4) 4 Feedback RBA 

8 + (N-1)(14) 6 Feedback volume serial number 
18+ (N-1)(14) 6 RBA/RRN argument 


The value for K is always 4 in an entry-sequenced or relative record 
data set. Therefore, 10+ K is always 14 for these two types of data 
sets. The maximum number of arguments allowed is 255. 


Chapter 2. VSAM Macro Formats and Examples 57 


CNVTAD 


ECB = address 
specifies the address of an event control block (ECB) which you may 
specify. VSAM indicates in the ECB whether or not a request is 
complete. This parameter is optional. 


OPTCD =({ADR|KEY} 
,(ASY|SYN} 
{KEQ|KGE} 

.FKS) 


ADR is only valid for entry-sequenced data sets. 


KEY is only valid for key-sequenced data scts and relative record dat 
a sets. 


If ASY is specified, you cannot WAIT on the RPLECB field for 
MNTACQ or ACQRANGE. You use the address placed in the 
parameter list feedback area. This address points to a list of ECBs (in 
standard WAIT list format) which you may use in place of the 
RPLECB field. 


GEN is not supported; if specified, it will give an error indication. 


All other OP FED subparameters are not applicable, and, if specified, 
are ignored with no crror indications. 


For a given list of discrete arguments, CNVTAD returns the volume serial 
number (volser) and the RBA corresponding to each argument in the parameter 
list feedback area. The data portion of your VSAM data set is not referenced and 
need not be mounted even if the sequence set is embedded. 


For an entry-sequenced data set, the volser is returned, and the same RBA 
specified in the argument ficld is also returned. 


Note: The RBA retumed by CNVTAD in the case of a key-sequenced data set 
is not the exact RBA of the record. It is, in fact, an approximate value. (For 
data sets with the IMBED option, it is the RBA of the beginning of the sequence 
set for the record’s control area; for data sets with NOIMBED, it is the RBA of 
the record’s control interval.) When passed to MNTACQ, these RBA values 
cause MNTACQ to stage the appropriate cylinders corresponding to the 
requested arguments originally passed to CNVTAD. You should therefore use 
caution if you are planning to use the RBAs obtained from CNVTAD for any 
purpose other than as input to MNTACQ. 


At the conclusion of this macro, the RPL is disconnected. Any positioning in 


effect prior to execution of this macro will be lost. You may have to reposition. 
Chained RPLs are not supported by CNVTAD. 
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DLVRP Macro (Delete VSAM Resource Pool) 


The DLVRP macro has a standard form and an execute form. The standard 
form builds a parameter list and passes control to VSAM to delete the resource 
pool. The execute form is described in Appendix B, “List, Execute, and 
Generate Forms of Macros” on page 171. 


The format of the DLVRP macro is: 


DLVRP | TYPE = {LSR/GSR} 


[, MODE = (24]31)] 
| SHRPOOL = {0|nwmnber}| 





TYPE = {LSR|GSR} 
specifies the type of resource pool to be deleted: local (ISR) or global 
(GSR). When deleting an LSR pool, the number spccificd on the 
SIIRPOOL parameter indicates which LSR pool is to be deleted. If both a 
data resource pool and an index resource pool have the same SIIRPOOL 
numbcr, both will be deleted. The program that issues DLVRP 
TYPE=GSR must be in supervisor state with protection key 0 to 7. 


MODE = (24|31} 
specifies the format of the DLVRP parameter list that is to be gencrated. 


24 
specifics that a standard form (24-bit) parameter list address be built. 
This parameter list must reside bclow 16 megabytes and contain the 
address of ACBs residing below 16 megabytes. The caller, however, 
may be above 16 megabytcs. This is the default paramctcr list 
format. 


31 
specifies that a long form (31-bit) parameter list address be built. 
This list can reside above or below 16 megabytes. This parameter 
value must be coded if the parameter list resides above 16 megabytes 
or contains the address of a VSAM/VTAM ACB residing above 16 
megabytes. 


SHRPOOL = (0|nwmber} 
specifics the identification numbcr of the shared resource pool that is to be 
deleted. Valid only when TYPE = LSR is also specified. ‘The DLVRP 
parameter list may reside above or below 16 megabytes. 


0 
specifics the shared pool with the identification of 0. This is the 
default LSR pool identification number. 

number 


specifies the shared pool with the identification of munber whcre 
number is a number from 0 to 15. 
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| Example: DLVRP Macro 


| This example shows how an LSR pool with a parameter list that may reside 
| above 16 megabytes and identification number other than 0 is deleted. 


DELPOOL DLVRP TYPE=LSR, 
l MODE=31, 
SHRPOOL=1 


The DLVRP parameters are: 
e TYPE specifies that an LSR pool is to be deleted. 


| ¢ MODE=31 specifies the parameter list may reside above or below 16 
| megabytes. 


| e SHRPOOL spccifies that the data resource pool and the index resource pool 
| (if any) with the identication number of | are to be deleted. 
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ENDREQ Macro (Terminate a Request) 


The format of the ENDREQ macro is: 


|/abe} | ENDREQ RPL = address 


where: 


label 
is 1 to 8 characters that provide a symbolic address for the ENDREQ 
"macro. 


RPL = address 
specifies the address of the request parameter list that defines the request. 
You may specify the address in register notation (using a register from 1 
through 12, enclosed in parentheses) or specify it with an expression that 
gencrates a valid relocatable A-type address constant. 


Note: The ENDREQ macro must not be issued when records are being loaded 
into a VSAM data set (load modc). ENDREQs issued while in load mode are 
ignored. 


Example: Reicase Positioning for Another Request 


In this exampic, the ENDREQ macro is used to cause VSAM to release 
exclusive control of a control interval containing a record. There are two request 
parameter lists, both of which require VSAM to have the ability to remember its 
position until VSAM is explicitly requested to forget its position. 


BLOCK ACB MACRF=(SEQ, 


DIR) , STRNO=2 
SEQ RPL ACB=BLOCK, VSAM must remember its 
OPTCD=SEQ position. 
DIRUPD RPL ACB=BLOCK, VSAM must remember its 
OPTCD=(DIR,UPD) position and maintain 
- exclusive control until 
; explicitly requested to 
é forget it by PUT or 
ENDREQ. 
LOOP GET RPL=SEQ VSAM now remembers its 
position for this request 
LTR 15,15 only while it is 
Ke processing the request. 
BNZ ERROR 
GET RPL=DIRUPD VSAM can remember its 
position for this request. 
LTR 15,15 The control interval will 
be placed in exclusive 
BNZ ERROR control until either 
ENDREQ or PUT UPD is 
issued. 
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Decide whether to update the record. 


B . FORGET No; do not update the 
record. 
PUT RPL=DIRUPD Yes; update the record, 
causing VSAM to forget its 
LTR 15,15 position for DIRUP. 
BNZ ERROR 
B LOOP 
FORGET ENDREQ RPL=DIRUPD Cause VSAM to forget its 
position for DIRUPD. 
LTR 15,15 Release exclusive control. 
BNZ ERROR 
B LOOP 
ERROR XXX Request wasn't accepted or 
failed. 


The use of ENDREQ illustrated here causes VSAM to release exclusive control 
of the control interval for a record. When PUT is issued after a DIRUPD GET 
request, ENDREQ need not be issued, because PUT causes VSAM to releasé 
exclusive control (the next DIRUPD GET doesn’t depend on VSAM’s 
remembering its position). Another result of ENDREQ is that current buffers 
are written if they have been modified. 


To cause VSAM to give up its position associated with a chain of request 
parameter lists, specify the first request parameter list in the chain in your 
ENDREQ macro. 


ENDREQ can also be used to cancel an asynchronous request, rather than 
suspending processing with CHECK. 


Note: If you are sharing subtasks or if you have issued an asynchronous request 
for access to a data set, you must issue a CHECK or an ENDREQ on all RPLs 
before you issue a CLOSE or CLOSE TYPE =T; otherwise, concurrent data set 
I/O activity will cause unpredictable results during a close. in is adequate. 


Because VSAM remembers its position after a direct GET with OPTCD= UPD 


or LOC, if no PUT or ENDREQ follows, you can switch to sequential access 
and use the positioning for a GET. 


62 MVS/XA VSAM Administration: Macro Instruction Reference 


ERASE 


ERASE Macro (Delete a Record) 


The format of the ERASE macro is: 


[fabef =| ERASE | RPL= address 


whcere: 


label 
is 1 to 8 characters that provide a symbolic address for the ERASE macro. 


RPL= address . 
specifics the address of a request paramctcr list that defines the request. 
You may specify the address in register notation (using a register from 1 
through 12, enclosed in parentheses) or specify it with an expression that 
generates a valid relocatable A-type address constant. 


With ERASE processing of key-sequenced data sets, VSAM attempts to make 
the control interval available to the control arca when the last record in the 
control interval is crascd. ‘Thus, key-sequenced data sct control intervals can be 
reused for new records whose keys fall anywhere within the control arca’s range 
of keys. You may suppress the process of reclaiming the control interval by 
setting RPILNOCIR in the RPL used for ERASE. The high key control interval 
of a control area is never reclaimed. 


Example 1: Keyed-Direct Deletion 


In this example, GET and ERASE macros are used to retrieve and delete records. 
Not every record retrieved for delction is deleted. The scarch argument is a full 
key (5 bytes), compared equal. 


DELETE ACB MACRF=(KEY, DIR, 
OUT) 


LIST RPL ACB=DELETE, 
AREA=WORK, 
AREALEN=50, 
ARG=KEYFIELD, 
OPTCD=(KEY, DIR, j 
SYN,UPD, UPD indicates deletion. 
MVE,FKS, 
KEQ) 


LOOP MVC KEYFIELD,source Search argument for 
retrieval, from a table 
or transaction record. 
GET RPL=LIST 
LTR 15,15 


BNZ ERROR 


: o, 
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Decide whether to delete the record. _ 


BE LOOP No; retrieve the next record. 
ERASE RPL=LIST Yes; delete the record. 
LTR 15,15 
BNZ ERROR 
B LOOP | 
ERROR er Request was not accepted, or 
failed. 
WORK DS CL50 Examine the data record here. 
KEYFIELD DS CL5 Search argument. 


When you retrieve a record for deletion (OPTCD = UPD, same as retrieval for 
update), VSAM is positioned at the record retrieved, in anticipation of a 
succeeding ERASE (or PUT) request for that record. You arc not required to 
issue such a request, though. Another GET request nullifics any previous 
positioning for deletion or update. 


Keyed-sequential retrieval for deletion varies from direct in not using a scarch 
argument (except for possible use of the POINT macro). Skip-sequential 
retrieval for deletion (OPTCD =(SKP,UPD)) has the same effect as direct, but it 
is faster or slower depending on the number of control intervals separating the 
records being retrieved. 


Example 2: Addressed-Sequential Deletion 
In this example, the ERASE macro is used to delete records from a 


key-sequenced data sct. Not every record retrieved for deletion is deleted. 
Skipping is effected by the POINT macro. 


DELETE ACB MACRF=(ADR, SEQ, 
OUT) 
REQUEST RPL ACB=DELETE, 
AREA=WORK, 
' AREALEN=100, 
ARG=ADDR, 
OPTCD=( ADR, SEQ, 
ASY, 
UPD , MVE) UPD indicates deletion. 
LOOP a Decide whether you need to 
skip to another position 
forward or backward). 
B RETRIEVE No; bypass the POINT. 
MVC ADDR, source Yes; move search argument 


for POINT into 
search-argument field. 
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POINT 


LTR 
BNZ 
CHECK 
LTR 
BNZ 
RETRIEVE GET 
LTR 
BNZ 
CHECK 
LTR 
BNZ 


RPL=REQUEST 


15,15 
ERROR 
RPL=REQUEST 
15,15 
ERROR 
RPL=REQUEST 
15,15 
ERROR 
RPL=REQUEST 
15,15 
ERROR 


Decide whether to delctc the record. 


BE 
ERASE 
LTR 
BNZ ' 
CHECK 
LTR 
BNZ 


ERROR 


ADDR DS 
WORK DS 


LOOP 
RPL=REQUEST 
15,15 

ERROR 
RPL=REQUEST 
15,15 

ERROR 

LOOP 


F 
CL100 


ERASE 


Position VSAM to the 
record to be retrieved 
next. : 


No; skip ERASE and CHECK. 


Yes; delete the record. 


Request was not accepted, 
or failed. 


RBA search argument for 
POINT. 
Work area. 


Addressed deletion is allowed only for a key-sequenced data sct. The records of 
an entry-sequenced data set are fixed. When records are deleted using addressed 
deletion from a key-scquenced data set, the index is not updated. 
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EXLST Macro (Generate an Exit List at Assembly Time) 


The format of the EXLST macro is: 


[/abe4 EXLST | [AM=VSAM] 
[,EODAD = (addressf, AINIL,LD] 
|, IOPID = (address)] 
LJRNAD = (address{,A|NILLDI 


_LLERAD = (addressf,A[NILLDI 
|, SYNAD = (addressf, A|NILLDI 
L,UPAD = (addressf, AINILLDI 





Valucs for EXLST macro subparameters can be specificd as absolute numeric 
expressions, character strings, codes, and expressions that gencrate valid 
rclocatable A-type address constants. 


| Note: Sce Data Facility Product: Customization for the factors that determine 
| the addressing mode and the parameter list residency mode set when the exit 
| routine gets control. : 


label , 
is | to 8 characters that provide a symbolic address for the exit list that is 
established. 


AM = VSAM 
specifics that the access method using the control block is VSAM. 


EODAD = (address{, AINILLDP 
IOPID = (address) 
JRNAD = (addressf, AINILLD 
LERAD = (address{,AINI[,LD 
SYNAD = (addressf,AINILLD 
UPAD = (address{,A|NI,A)) 
specify that you are supplying a routine for the exit specified. 


| For more information about user exit routines, see Data Facility Product: 
| Customization. 


The exits and values that can be specified for these routines are: 


EODAD 
specifies that an exit is provided for special processing when the end 
of a data set is reached by sequential access. 


IOPID 
specifies that an I/O prevention identifier is provided to terminate I/O 
and prevent new I/O from being started for the data sets associated 
with the identifier. When the IOPID address is specified, the 
identifier is always assumed to be active. 
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Example: EXLST Macro 


EXLST 


JRNAD 
specifies that an exit is provided for journalizing transactions as you 
process data records. a 


LERAD 
specifies that an exit is provided for analyzing logical errors. 


SYNAD . 
specifics that an exit 1s provided for analyzing physical errors. 


UPAD 
specifies that an exit 1s provided for user processing during a VSAM 
request. The GENCB, MODCB, SHOWCEB, and TESTCB macros 
do not support the UPAD user exit routine. 


address 
is the address of a uscr-supplicd exit routine or an I/O prevention 
identificr. The address must immediately follow the cqual sign. 


A|N 
specifics that the exit routine is active (A) or not active (N). VSAM 
docs not enter a routine whose cxit is marked not active. 


specifics that the address is that of an 8-byte ficld that contains the 
name of an exit routine in a partitioned data sct that is identificd by a 
JOBLIB or STEPLIB DD statement or in SYS1-.LINKLIB. VSAM 
is to load the exit routine for exit processing. If L is omitted, the 
address gives the entry point of the exit routine in virtual storage, and 
the exit routine is entered in the addressing mode of the VSAM caller. 


In this example, an EXLST macro is used to identify exit routines that are 
provided for analyzing logical and physical errors. The label, EXITS, of the 
EXLST macro is used in an ACB or GENCB macro that gencrates an access 
method control block to associate the exit list with an access method control 
block. The exit list generated by this example is built when the program is 
assemblcd. 


EXITS EXLST EODAD=(ENDUP,N), EXITS gives symbolic 


LERAD=LOGICAL, address of the exit list. 
SYNAD=( ROUTNAME, L) 

ENDUP EODAD routine. 

LOGICAL LERAD routine. 

ROUTNAME DC C' PHYSICAL' Pad shorter names with 


blanks: C'SYN'or CL8'SYN’. 


The EXLST macro’s parameters are: 


@ EODAD specifies that the end-of-data routine is located at ENDUP and is 
not active. 
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e LERAD specifies that the logical error routine is located at LOGICAL and is 
active. 


e SYNAD specifies that the physical error routine’s name is located at 
ROUTNAME. 
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| GENCB Macro (Generate an Access Method Control Block at 


| Execution Time) — 


The format of the GENCB macro used to generate an access method control 


block 1s: 


[label 


GENCB | BLK= ACB 


|,AM = VSAM] 
|, BSTRNO = number] 
|, BUFND = number} 
|, BUFNI = number] 
|,BUFSP = number| 
| ,CATALOG = YES/NO] 
|,COPIES = number] 
j,CRA = SCRA|UCRA] 
[|,DDNAME = ddname] 
[EXLST= address] 
| ,LENGTH = number| 
{LOC = BELOW[ANY] 
[ MACRF = ({ADR][,CNV]],.KEY] 
[,CFX|NFX} 
|,.DDNIDSN] 
|, DFRINDF] 
[, DIR}, SEQUSKP} 
LICINCY 
LINJLOUT] 
[ NIS|SIS| 
J NRMJATX] 
|. NRSIRST] 
| NSRILSRIGSR| 
|, NUB|UBED] 


| 1 MAREA= address} 


|, MLEN = number] 

{,PASSWD = address] 

|,.RMODE3!1 = {ALL|BUFF|CB|NONE}] 
|, SHRPOOL = {0|nwmber}] 

|, STRNO = number] 

|, WAREA = address] 


Note: The RMODE parameter replaces the AMODE31! subparamceter used in 
previous releases. 


The subparametcrs of the GENCB macro can be expressed as absolute numeric 
expressions, as character strings, as codes, as expressions that gencrate valid 
relocatable A-type address constants, in register notation, as S-type address 
constants, and as indirect S-type address constants. Appendix C, “Operand 
Notation” on page 181, further defines these operand expressions. 


label 


is 1 to 8 characters that provide a symbolic address for the GENCB macro. 
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eo o 


BLK = ACB 
specifies that you are generating an access method control block. 


AM = VSAM 
specifies that the access method using this control block is VSAM. 


BSTRNO = number 
specifies the number of strings initially allocated for access to the base 
cluster of a path. The default is STRNO. BSTRNO is ignorcd if the 
object being opencd is not a path. If the number specified for BSTRNO is 
insufficient, VSAM will dynamically extend the number of strings as needed 
for the access to the base cluster. BSTRNO can also influence 
performance. -The VSAM control blocks for the set of strings specified by 
BSTRNO are allocated on contiguous virtual storage, whereas this is not 
guaranteed for the strings allocated by dynamic extension. 


BUFND = number 
specifics the number of I/O buffers VSAM is to use for transmitting data 
between virtual and auxiliary storage. A buffer is the size of a control 
interval in the data component. The minimum number you may specify is 
1 plus the number specified for STRNO (if you omit STRNO, BUFND 
must be at Icast 2, because the default for STRNO is 1). The number can 
be supplied by way of the JCL DD AMP parameter as well as by way of 
the macro. The default is the minimum number required. A larger number 
for BUFND can improve the performance of sequential access. 


BUFNI = number 
specifies the number of I/O buffers VSAM is to use for transmitting index 
entrics between virtual and auxiliary storage for keyed access. A buffer is 
the size of a control interval in the index. The minimum number is the 
number specified for STRNO (if you omit STRNO, BUFNI must be at 
least 1, because the default for STRNO is 1). You can supply the number 
by way of the JCL DD AMP parameter as well as by way of the macro. 
The default is the minimum number required. A larger number for BUFNI 
can improve the performance of keyed-direct retrieval. 


BUFSP = number 
specifies the maximum number of bytes of virtual storage to be used for the 
data and index I/O buffers. VSAM gcts the storage in your program's 
address space. If you specify less than the amount of space that was 
specified in the BUFFERSPACE parameter of the DEFINE command 
when the data set was defined, VSAM overrides your BUFSP specification 
upward to the value specified in BUFFERSPACE. (BUFFERSPACE, by 
definition, is the least amount of virtual storage that will ever be provided 
for I/O buffers.) You can supply BUFSP by way of the JCL DD AMP 
parameter as well as by way of the macro. If you don’t specify BUFSP in 
either placc, the amount of storage used for buffer allocation is the /argest 
of: 


e The amount specified in the catalog (BUFFERSPACE), 


e The amount determined from BUFND and BUFNI, or 
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@ The minimum storage required to process the data sct with its specified 
processing options 


If BUFSP is specified and the amount is smaller than the minimum 
amount of storage required to process the data set, VSAM cannot open the 
data set. 


A valid BUFSP amount takes precedence over the amount called for by 
BUFND and BUFNI. If the BUFSP amount is greater than the amount 
called for by BUFND and BUFNI, the extra space is allocated as follows: 


@ When MACRF indicates direct access only, additional index buffers are 
allocated. 


@ When MACREF indicates sequential access, one additional index buffer 
and as many data buffers as possible are allocated. 


If the BUFSP amount is less than the amount called for by BUF ND and 
BUFNI, the number of data and index buffers is decreased as follows: 


@ When MACREF indicates dircct access only, the number of data buffers 
is decrcascd to not Iess than the minimum number. Then, if required, 
the number of index buffers is decreased until the amount called for by 
BUFND and BUFNI complies with the BUFSP amount. 


e When MACREF indicates sequential access, the number of index buffers 
is decreased to not Iess than 1 more than the minimum number. Then, 
if required, the number of data buffers is decreased to not less than the 
minimum number. If still required, 1 more is subtracted from the 
number of index buffers. 


@® Neither the number of data buffers nor the number of index buffers is 
decreased to less than the minimum number. 


if the index doesn’t exist or isn’t being opened, only BUF/ND, and not 
BUFNI, enters into these calculations. 


CATALOG = YES|NO 
specifics whcther a catalog is being opencd as a catalog (YES) or as a data 
set (NO). When NO is coded (or taken as the default), you can process the 
catalog with request macros (GET, PUT, ctc.). To open a 
password-protected catalog for processing with VSAM macros, you must 
supply its master password. When CATALOG= YIES is coded, the catalog 
must be processed with an SVC designed for that purpose. (Access method 
services, for example, processes catalogs with SVC 26.) The request macros 
are invalid for processing a catalog ‘“‘as a catalog.” VSAM users should alter 
the contents of a catalog only by access mcthod services commands. 


-COPIES = number 
specifics the number of copies of the access method control block VSAM is 
to generate. All the copies are identical. You can use MODCB to tailor 
each one for the data set and processing you want for it. MODCB is 
described later in this chapter. 
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CRA=SCRA|UCRA 
specifies that a catalog recovery area is to be opened and that the control 
blocks are to be built in either system storage (SCRA) or user storage 
(UCRA). If you specify SCRA and issue record management requests, you 
must operate in key 0. If you specify UCRA, you must be authorized by 
the system and you must supply the master password of the master catalog. 


DDNAMIE = ddname 
is | to 8 characters that identify the data set that you want to process by 
specifying the JCL DD statement for the data set. You may omit 
DDNAME and provide it by way of the MODCB macro before opening 
the data set. MODCB is described later in this chapter. 


EXLST = address 
specifies the address of a list of addresses of exit routines that you are 
providing. The list is established by the EXLST or GENCB macro. If you 
use the EXLST macro, you can specify its label here as the address of the 
exit list. If you use GENCB, you can specify the address returned by 
GENCB in register 1. Omitting this parameter indicates that you have no 
exit routines. Exit routines are described in the chapter “User-Written Exit 
Routines” in Data Facility Product: Customization. 


LENGTH = number 
specifies the length, in bytes, of the area, if any, that you are supplying for 
VSAM to generate the access method control block(s). (See the WAREA 
paramcter.) When the LENGTH value is specified, it cannot exceed 65535 


(X'FFFF'). 
LOC = BELOW|[ANY 


BELOW 
specifies that VSAM is to construct an ACB in an arca of virtual 
storage below 16 megabytes at execution time. This is the default. 


ANY 
specifies that VSAM is to construct an ACB in an area of virtual 
storage above 16 megabytes, if possible, at execution time. 


MACRF = ([ADR][,CNV]L KEY} 

|, CFX|NEX] 

| DDNIDSNI 

LE. DFR|INDF] 

[, DIRISEQI,SKP} 

LICIINCH 

LINJLOUT] 

[ NIS|SIS] 

|. NRM]AIX] 

_ [NRSIRST] 

| NSRILSRIGSR| 

| NUB|UBFD) 
specifies the kind(s) of processing you will do with the data set. The 
subparameters must be meaningful for the data set. For example, if you 
specify keyed access for an entry-sequenced data set, you cannot open the 
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data sct. You must specify all the types of access you’re going to use, 
whether you use them concurrently or by switching from one to the other. 
The subparameters are shown in Figure 12 on page 38. They are arranged 
in groups, and each group has a default value (indicated by underlining). 
You may specify subparameters in any order. You may specify both ADR 
and KEY to process a key-sequenced data set.. You may specify both DIR 
and SEQ; with keyed access, you may specify SKP as well. If you specify 
OUT and want merely to retrieve some records as well as update, delete, or 
insert others, you nced not also specify IN. 


Note: The RMODE3] parameter replaces the AMODE31 subparameter 
used in previous releases. 


MAREA = address 
specifics the address of an optional OPEN/CLOSE or TYPE=T option 
(CLOSE macro) message area. 


MLEN = nurnber 
specifics the Icngth of an optional OPEN/CLOSE or TYPE=T option 
(CLOSE macro) message area. 


PASSWD = address 
specifies the address of a field that contains the highest-level password 
required for the type(s) of access indicated by the MACRF parameter. The 
first byte of the ficld contains the Iength (in binary) of the password 
(maximum of 8 bytes). Zero indicates that no password is supplicd. If the 
data sct is password protected and you don’t supply a required password in 
the access method control block, VSAM may give the console operator the 
opportunity to supply it when you open the data sct. 


RMODE3!1 = {[ALL|BUFF|CBIN ONE} 
specifies where VSAM OPEN is to obtain virtual storage (above or below 
16 megabytes) for contro! blocks and I/O buffers. 


The values specificd by the RMODE3! parameter only have an effect on 
VSAM at the setting just before an OPEN is issued. At all other times, . 
changing these values has no effect on the residency of the control blocks 
and I/O buffers. 


The virtual storage location of the ACB is independent of the RMODE31 
parameter. An ACB may reside cither above or bclow 16 megabytes. 


ALL 
both VSAM control blocks and I/O buffers are to be obtained above 
16 megabytes. 

BUFF 
only VSAM I/O buffers are to be obtained above 16 megabytes. 


CB 
only VSAM control blocks are to be obtained above 16 megabytes. 
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NONE 
both- VSAM control blocks and I/O buffers are to be obtained below 
16 megabytes. This is the default. 


SHRPOOL = {mwnber|0} 
specifics the identification number of the resource pool to be used for LSR 
processing. The default is SYRPOOL=0. 


STRNO = nwnber 
specifics the number of requcsts requiring concurrent data sect positioning 
VSAM is to be prepared to handle. A request is defined by a given request 
parameter list or chain of request parameter lists. See “RPL Macro 
(Gencrate a Request Parameter List at Assembly Time)” on page 126 and | 
“GENCB Macro (Generate a Request Paramcter List at Execution Time)” 
on page 80 for information on request parameter lists. 


WAREA = address 
specifics the address of an area in which to generate the access method 
control block(s). 


The arca must begin on a fullword boundary. 


This parameter is paired with the LENGTII parameter. You must supply 
the LENGTH parameter if you specify an area address. 


Note: If you do not specify an area in which the access method control 
block is to be generated, VSAM obtains virtual storage space for the area 
(as specified by the LOC = keyword). VSAM returns the address of the 
arca containing the control block(s) in register | and the Icngth of the area 
in register 0. You can find out the length of cach control block by dividing 
the Icngth of the area by the number of copics. Vhe address of each control 
block can then be calculated by this offset from the address in register 1. 
You can find the Iength of an access mcthod control block with the 
SHOWCB macro. 


If you are generating control blocks by issuing several GENCBs, specifying 
an area (WAREA and LENGTH parameters) for them enables you to 
address all of them with one base register and to avoid repetitive requests 
for virtual storage. 
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Example: GENCB Macro (Generate an Access Method Control Block) 


In this example, a GENCB macro is used to identify a data set to be opened and 
to specify the types of processing to be performed. This example specifics that 
the space for the control block be obtained above 16 megabytes. The access 
method control block. generated by this example is built when the program is 
executed. 


GENCB GENCB BLK=ACB,AM=VSAM, One copy generated; VSAM 
BUFND=4,BUFNI=3, gets the storage for it, 


BUFSP=19456, because the WAREA LENGTH 

DDNAME=DATASETS, parameters have been 

EXLST=EXITS, omitted. 

LOC= ‘ 

MACRF=(KEY, DIR, 

SEQ,OUT), 

PASSWD=FIELD, 

RMODE31=ALL, 

STRNO=2 

ST 1, ACBADDR Save the address of the 
access method control 
block. 
ACBADDR DS F The address of the 


access method control 
block is saved in 
ACBADDR. 


FIELD DC FL1'6',C'CHANGE' CHANGE, the password, has 
6 characters. 


The GENCB macro’s parameters are: 


@¢ BUEFND specifics four I/O buffers for data; BUFNI specifics three I/O 
buffers for index entries; and BUFSP specifics 19456 bytes of buffer space, 
enough space to accommodate control intervals of data that are 4096 bytes 
and of index entries that are 1024 bytes. 


e¢ DDNAME specifies that this access method control block is associated with 
a DD statement named DATASETS. 


e EXLST specifics that the exit list associated with this access method control 
block is named EXITS. 


e LOC spccifics that VSAM obtain virtual storage for the ACB from an arca 
that may be above 16 mcgabytcs. 


e MACRF specifies keyed direct and keyed sequential processing for both 
inscrtion and update. 


e PASSWD spccifies the location, FIELD, of the password provided. 


¢ RMODE3!] specifies that VSAM obtain storage for the VSAM control 
blocks and I/O buffers in an area above 16 megabytes when the ACB Is 
opened. 


e STRNO specifies that two requests will require concurrent positioning. 
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| GENCB Macro (Generate an Exit List at Execution Time) 


——— 


The format of the GENCB macro used to generate an exit list is: 


[abel =| GENCB | BLK=EXLST 
[,AM = VSAM] 
[ EODAD = (addressf, AINILLD] 
[SRNAD = (address|,A|NILLD| 
[,LERAD = (address|,AINILLD] 


[ SYNAD = (addressf, AJNILLDI 
[,COPIES = number] 

|, LENGTH = number| 

[,LOC = BELOW|ANY] 
[,WAREA = address| 





The parameters of the GENCB macro can be expressed as absolute numcric 
expressions, as character strings, as codes, as expressions that gencrate valid 
relocatable A-type address constants, in register notation, as S-type address 
constants, and as indirect S-type address constants. Appendix C, “Opcrand 
Notation” on page 181, further defines these operand expressions. 


Note: See Data Facility Product: Customization for the factors that determine 
the addressing mode and the parameter list residency mode set when the exit 
routine gets control. 


label 
is | to 8 characters that provide a symbolic address for the GENCB macro. 


BLK = EXLST 
specifies that you are generating an exit list. 


AM = VSAM 
specifies that the access method using this control block is VSAM. 


[ EQDAD = (addressf,A|N][LD] 
|, JRNAD = (address{,AINILL)] 
|,.LERAD = (addressf, AINILLDI 
| SYNAD = (addressf,AINILLDI 
specify that you are supplying a routine for the exit named. 


For more information about user exit routines, see Data Facility Product: 
Customization. 


If nonc of these user exit routines is specified, VSAM generates an exit list 
with inactive entrics for all the exits. The exits and values that can be 
specified for them are: 


EODAD 
specifies that an exit is provided for special processing when the end 
of a data set is reached by sequential access. 
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JRNAD 
specifies that an exit is provided for journaling as you process data 
records. 


LERAD 
specifies that an exit 1s provided for analyzing logical errors. 


SYNAD 
specifics that an exit is provided for analyzing physical errors. 


address 
is the address of a user-supplied exit routine. The address must 
immediately follow the equal sign. 


A|N 
specifies that the exit routine is active (A) or not active (N). VSAM 
does not enter a routine whose exit is marked not active. 


specifies that the address is that of an 8-byte field that contains the 
name of an exit routine in a partitioned data sct that 1s identificd by a 
JOBLIB or STEPLIB DD statement or in SYS1.LINKLIB. VSAM 
is to load the exit routine for exit processing. If L is omitted, the | 
address gives the entry point of the exit routine in virtual storage, and 
the exit routine is entered in the addressing mode of the VSAM caller. 
L may precede or follow the A or N specification. 


COPIES = number 
specifies the number of copies of the exit list you want gencrated. GENCB 
generatcs as many copics as you specify (default is 1) when your program is 
executed. All copies are the same. You can use MODCB to change some 
or all of the addresses in a list. (MODCB is described later in this chapter.) 


LENGTH = number 
specifies the length, in bytes, of the area, if any, that you are supplying for 
VSAM to generate the exit list(s). (See the WAREA parameter.) When 
the LENGTH value is specified, it cannot exceed 65535 (X ‘FFFF'). 


LOC = BELOW|ANY 


BELOW 
specifics that VSAM is to construct an exit list in an area below 16 
megabytes at execution time. This is the default value. 


ANY 
specifics that VSAM is to construct an exit list in an area above 16 
megabytes, if possible, at execution time. 


WAREA = address 
specifies the address of an area in which the exit list(s) is to be generated. 


The area must begin on a fullword boundary. 


Chapter 2. VSAM Macro Formats and Examples 77 


GENCB—EXLST 


This parameter is paired with the LENGTH parameter, which must be 
given if you specify an area address. 


Note: If you did not specify an area in which the exit list is to be 
gencrated, VSAM obtains virtual storage space for the area (as specified by 
the LOC = keyword). VSAM returns the address of the area in which the 
exit lists(s) is to be generated in register 1, and the length of the area in 
register 0. You can find the length of each exit list by dividing the length of 
the area by the number of copies. The address of each exit list can then be 
calculated by this offset from the address in register 1. You can find the 
Iength of an exit list with the SHOWCB macro, described under 
“SILOWCB Macro (Display Fields of an Exit List)” on page 139. 


If you are gencrating control blocks by issuing several GENCBs, specifying 
an area (WAREA and LENGTH) for them enables you to address all of 
them with one base register and to avoid repetitive requests for virtual 
storage. , 


Example: GENCB Macro (Gencrate an Exit List) 


In this example, a GENCB macto is used to gencrate an exit list when the 
program is exccuted. 


EXITS GENCB BLK=EXLST, 


EODAD=(EOD,N), 
LERAD=LOGICAL, 
SYNAD=(ERROR, 


A,L) 

LTR 15,15 

BNZ ERROR 

ST 1,EXLSTADR Address of the exit list is saved. 
EOD EQU. * EODAD routine. 
LOGICAL EQU #* LERAD routine. 
ERROR DC C' PHYSICAL' Name of the SYNAD module. 
EXLSTADR DS F Save area for exit-list address. 


The GENCB macro’s parameters are: 


BLK specifies that an exit list is to be generated. 


EODAD specifies that the end-of-data routine is located at EOD and is not 
active. 


LERAD specifies that the logical error routine is located at LOGICAL; 
because ncither A nor N is specificd, the LERAD routine is marked active by 
default. 


SYNAD specifies that the physical error routine’s name is located at 
ERROR. 
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_ Because no area was specified in which the exit list was to be. generated, VSAM 

obtained virtual storage for the exit list and returned the address in register 1. 
Immediately after the GENCB macro, the address of the exit list, contained in 
register 1, is moved to EXLSTADR. EXLSTADR may be specified in a 
GENCB macro that generates an access method control block or in a MODCB, 
SHOWCB, or TESTCB macro that modifies, displays, or tests ficlds in an exit 
list. 
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| GENCB Macro (Generate a Request Parameter List at Execution 
| Time) 


The format of the GENCB macro used to generate a request parameter list is: 


GENCB | BLK=RPL 
[, ACB = address] 
[,AM = VSAM] 
|, AREA = address] 
|, AREALEN = number] 
[,ARG = address] 
[,COPIES = number] 
[,ECB = address} 
| KEYLEN = number] 
[,.LENGTH = nzumber| 
| [,LOC = BELOW[ANY] 
[| MSGAREA = address] 
[, MSGLEN = number] 
[| NXTRPL = address| 
[,OPTCD = ({ADR|CNV|KEY] 
[, DIR|SEQISKP} 
LARDILBD} 
[.FWD|BWD] 
LASY|SYN] 
[ NSP|NUP|UPD] 
L.KEQIKGE] 
LEKS|GEN| 
| ,LOC|MVE))] 
[,RECLEN = number} 
[,TRANSID = number] 
[, WAREA = address] 





The parameters of the GENCB macro can be expressed as absolute numeric 
expressions, as character strings, as codes, as expressions that generate valid 
relocatable A-type address constants, in register notation, as S-type address 
| constants, and as indirect S-type address constants. Appendix C, “Operand 
| Notation” on page 181 further defines these operand expressions. 


-The parameters of the GENCB macro to generate a request paramcetcr list are 

- Optional in some cases, but required in others. It is not necessary to omit 
parameters that are not required for a request; they are ignored. Thus, for 
example, if you switch from direct to sequential retrieval with a request parameter 
list, you don’t have to zero out the address of the field containing the scarch 
argument (ARG = address). 


label 
is | to 8 characters that provide a symbolic address for the GENCB macro. 
For addressing lists generated by GENCB, see the discussion of the 
COPIES parameter. - 
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BLK = RPL 
specifies that you are generating a request parameter list. 


ACB = address 
specifies the address of the access method control block that identifies the 
data set to which access will be requested. If you omit this parameter, you 
must issue MODCB to specify the address of the access method control 
block before you issue a request. (MODCB is described later in this 
chaptcr.) 


AM = VSAM 
specifies that the access method using this control block is VSAM. 


AREA = address 
specifies the address of a work areca to and from which VSAM moves a data 
record if you request it to do so (with the RPL parameter | 
OPTCD= MVE). If you request that records be processed in the I/O 
buffer (OPTCD = LOC), VSAM puts into this work area the address of a 
- data record within the 1/O buffer. 


AREALEN = number 
specifies the length, in bytes, of the work arca whose address is specificd by 
the AREA parameter. Its minimum for OPTCD= MVE is the size of a 
data record (or the largest data record, for a data set with records of variable 
Iength). For OPTCD=LOC, the area should be 4 bytes to contain the 
address of a data record within the I/O buffer. 


ARG = address 
specifies the address of a ficid that contains the scarch argument for direct 
retricval, skip-sequential retricval, and positioning. For a relative record 
data set, the ARG ficld must be 4 bytes long. For direct or skip-sequential 
processing, this field contains your search argument, a relative record 
number. For sequential processing (OPTCD = (KEY,SEQ)), the 4 bytes 
are requircd for VSAM £e¢ return the feedback RRN. For keyed access 
(OPTCD= KEY), the search argument is a full or generic key; for 
addressed access (OPTCD= ADR), it is an RBA. If you specify a generic 
key (OPTCD= GEN), you must also specify in the KEYLEN parameter 
how many of the bytes of the full key you are using for the generic key. 


COPIES = number 
specifies the number of copics of the request parameter list you want 
gencrated. GENCB generates as many copies as you specify (default is 1) 
when your program is exccutcd. 
The copies of a request parameter list can be used to: 


e Chain lists together to gain access to many records with one request 


e Define many requests to gain access to many parts of a data set 
concurrently 


All copies generated are identical; you must use MODCB to tailor them to 
specific requests. MODCB is described in this chapter. 
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ECB = address 
specifies the address of an event control block (ECB) that you may supply. 
VSAM indicates in the ECB whether a request is complete or not (using 
standard completion codes, which are described in Data Areas). You can 
use the ECB to determine that an asynchronous request is complete before 
issuing a CHECK macro. This parameter is always optional. 


KEYLEN = nwmber 
specifies the length, in bytes, of the generic key (OPTCD= GEN) you are 
using for a scarch argument (given in the ficld addressed by the ARG 
parameter). This parameter is required with a search argument that is a 
generic key. The number can be | through 255. For full-key searches, 
VSAM knows the key length, which is taken from the catalog definition of 
the data set when you open the data set. 


LENGTH = nwnber 
specifies the length, in bytes, of the area, if any, that you are supplying for 
VSAM to gencrate the request parameter list(s). (Sec the WAREA 
parametcr.) When the LENGTH value is specificd, it cannot exceed 65535 


(X"FFFF ‘). 


You can find out how long a request parameter list is with the SIOWCB 
macro, described later in this chapter. 


LOC = BELOW|ANY 


BELOW 
~~ specifies that storage for the RPL be obtained from virtual storage 
below 16 megabytes. This is the default value. 


ANY 
specifics that storage be obtained from virtual storage above 16 
megabytes if possible. 


MSGAREA = address 
specifies the address of an area that you are supplying for VSAM to send 
you a message in case of a physical error. (The format of a physical error 
message is given under “Physical Errors” in the chapter “Request 
Macros.”) 


MSGLEN = number 
specifies the size, in bytes, of the message area indicated in the MSGAREA 
parameter. The size of a message is 128 bytes; if you provide less than 128 


bytes, no message is returned to your program. This parameter is required 
when MSGAREA is coded. 
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_ NXTRPL = address 
specifies the address of the next request parameter list in a chain. Omit this 
parameter from the macro that generates the only or last list in the chain. 
When you issue a request that is defined by a chain of request parameter 
lists, indicate in the request macro the address of the first parameter list in 
the chain. A single request macro can be defined by multiple request 
parameter lists, such that a GET, for example, can cause VSAM to retrieve 
two or more records. 


OPTCD = ({ADR|CNV|KEY} 

[, DIR|SEQISKP] 

| ARD|LRD} 

-[L,.FWD|BWD] 

|, ASY|SYN] 

|, NSP|NUP|UPD} 

|, KEQIKGE] 

| FKS|GEN] 

{,LOC|MVE}) 

specifies the subparamcters that govern the requcst defined by the request. 
parameter list. Each group of subparameters has a default; subparameters 
arc shown in Figure 13 on page 128 with defaults underlined. Only onc 
subparameter from cach group is effective for a request. Some requests do 
not require an subparamceter from all of the groups to be specified. The 
groups that are not required are ignored; thus, you can use the same request 
parameter list for a combination of requests (GET, PUT, POINT, for 
example) without zeroing out the inapplicable subparameters each time you 
go from one request to another. 


RECLEN = number 
specifies the Iength, in bytes, of a data record being stored. If the records 
you are storing are all the same Icngth, you will not need to change 
RECLEN after you set it. This parameter is required for PUT requests. 
For GET requests, VSAM puts the length of the record retrieved in this 
ficid in the request paramcter fist. It will be there if you update and store 
the record. 


TRANSID = number 
specifics a number that relates modified buffers in a buffer pool. Use in 
shared resource applications and a description are in “Sharing Resources” 
in VSAM Administration Guide. 


WAREA = address 
specifics the address of an arca in which the requcst parameter list(s) is to 
be generated. 


The area must begin on a fullword boundary. 


This parameter is paired with the LENGTH parameter, which must be 
given if you specify an area address. 


Note: If you did not specify an area in which the request parameter list is 
to be generated, VSAM obtains virtual storage space for the area (as 
specified by the LOC=keyword). VSAM returns the address of the area in 
which the request parameter list(s) is generated in register 1, and the length 
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of the area in register 0. You can find the length of each list by dividing the 
length of the area by the number of copies. You can then calculate the 
address of each list by using the length of each list as an offset. 


If you are generating control blocks by issuing several GENCBs, specifying 
an area (WAREA and LENGTH parameters) for them enables you to 
address all of them with one base register and to avoid repetitive requests 
for virtual storage. 


Building a Chain of Request Parameter Lists 


When GENCB is uscd to build a chain of request parameter lists, the request 
parameter lists may be chained using only GENCB macros or using GENCB and 
MODCB macros together. When only GENCB is used, the request parameter 
lists are created in reverse order, as follows: 


SECOND re ee 
FIRST GENCB BLK=RPL, NXTRPL=(2) 


SECOND GENCE creates the second request parameter list, which makes its 
address available for the first request parameter list. ‘The address of the request 
parameter list is returned in register | and is loaded into register 2. FIRST 
GENCEB creates the first request parameter list and supplies the address of the 
ficxt request pararneter list using register notation. GENCB and MODCE 
macros may be used together to create a chain of request parameter lists, as 
follows: 


GENCB BLK=RPL, COPIES=2 
LR 2,0 

SRL 2,1 

LR 3,1 

LA 4,0(2,3) 

MODCB  RPL=(3),NXTRPL=(4) 


The GENCB macro creates two request parameter lists. The length of the 
parameter lists is returned in register 0 and loaded into register 2. The address of 
the area in which the lists were created (and, therefore, the address of the first 
one) is returned in register 1 and loaded into register 3. The SRL statement 
divides the total length of the area (register 2) by 2. The LA statement loads the 
address of the second request paramcter list into register 4. The MODCB macro 
modifies the first request parameter list (register 3) by supplying the address of the 
second request parameter list (register 4) in the NXTRPL paramcter. 


Each request parameter list in a chain should have the same OPTCD 
subparameters. Having different subparameters may cause logical errors. You 
can’t chain request parameter lists for updating or deleting records—only for 
retricving records or storing new records. You can’t process records in the I/O 
buffer with chained request parameter lists. (OPTCD = UPD and LOC are 
invalid for chained request parameter lists.) 
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Example: GENCB Macro (Gencrate a Request Parameter List) 


In this example, a GENCB macro is used to generate a request paramcter list. 


ACCESS 


ACCESS 
WORK DS 
SEARCH DS 
MESSAGE DS 


GENCB BLK=RPL, 
ACB=ACCESS, 
AM=VSAM, 
AREA=WORK, 
AREALEN=125, 
ARG=SEARCH, 
LOC=ANY, 
MSGAREA=MESSAGE, 
MSGLEN=128, 
OPTCD=(SKP, UPD) 


ACB MACRF=(SKP, OUT) 
CL125 
CL8 


CL128 


The GENCB macro’s parameters are: 


BLK specifies that a request parameter list is to be generated. 


ACB specifies that the request parameter list is associated with a data sct and 
processing options identificd by ACCESS. 


AREA and AREALEN specify a 125-byte work arca to be used for 
processing records. 


ARG specifies the address of the search argument. 


LOC specifics that VSAM obtain storage for the request parameter list in an 
area above 16 megabytes. 


MSGAREA and MSGLEN specify a 128-byte area to be used for 
physical-error messages. 


OPTCD specifies the subparameters that govern the request defined by the 
request parameter list identified by SKP and UPD. 


Chapter 2. VSAM Macro Formats and Examples 85 


GET 


GET Macro (Retrieve a Record) 


The format of the GET macro is: 


[/abeqj RPI = address 


where: 


label 
is | to 8 characters that provide a symbolic address for the GET macro. 


RPL = address 
specifics the address of the request parameter list that defines this GET 
request. You may specify the address in register notation (using a register 
from | through 12, enclosed in parentheses) or specify it with an expression 
that generates a valid relocatable A-type address constant. 


Example 1; Keyed-Sequential Retrieval (Forward) 


In this example, a GET macro is used to sequentially retrieve records by key. 
Retricval is in‘a forward direction. Fixed-length, 100-byte records are moved to a 
work area. Processing.is synchronaus. 


INPUT ACB MACRF=(KEY, All MACRF and OPTCD 
SEQ, IN) subparameters specified are 
defaults and could have 
been omitted. 


RETRVE RPL ACB=INPUT, 


AREA=IN, 
AREALEN=100, 
OPTCD=(KEY, SEQ, 
SYN, NUP, MVE) 

LOOP GET RPL=RETRVE This GET or identical GETs can 
be issued, with no change in 
the request parameter list, to 
retrieve subsequent records in 
key sequence. 

LTR 15,15 
BNZ ERROR 
B ‘LOOP 
ERROR whe Request was not accepted, or 
P failed. 
IN DS CL100 IN contains a data record after 


GET is completed. 
The records are retrieved in key sequence in a forward direction. No search 


argument has to be specified; VSAM is positioned at the first record in key 
sequence when the data set is opened, and the next record is retrieved 
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an 


GET 


automatically as each GET is issued. The branch to ERROR could also be 


taken if the end of the data set is reached. 


Example 2: Keyed-Sequential Retrieval (Backward) 


This example is the same as the previous one, except that a POINT macro 
instruction is issued to the last record in the data set and the records are retrieved 
in a backward dircction. 


INPUT ACB 


RETRVE RPL 


EXLST1 EXLST 
POINT 
LTR 
BNZ 

LOOP GET 
LTR 
BNZ 


EOD EQU 
ERROR 


IN DS 


Example 3: Skip-Scquential Retrieval 


DDNAME=INPUT, 
EXLST=EXLST1 


ACB=INPUT, 
AREA=IN, 
AREALEN=100, 
OPTCD=(KEY, SEQ, 
LRD, BWD) 
EODAD=EOD 
RPL=RETRVE 
15,15 

ERROR 
RPL=RETRVE 
15,15 


ERROR 


LOOP 


CL100 


Define RPL for last record 
positioning and backward 
processing. 


Define end of data. 


Position to last record (no 
argument is required). 


Get previous record. 


Come here for end of data. 


Request failed. 


Area for retrieved record. 


In this example, a GET macro is used to retrieve variable-length records 
synchronously. Records are to be processed in the I/O buffer. The search 
argument is full key, compared greatcr-than-or-equal; key length is cight bytes. 


The records are retricved in key sequence, but some records are skipped. 
Skip-sequential retrieval is similar to keyed-direct retrieval, except that you must 
retricve records in ascending sequence (with skips) rather than in a random 


sequence. 


GENCB 


LTR 


BLK=ACB, 
DDNAME=INPUT, 
MACRF=(KEY, 
SKP, IN) 


15,15 


VSAM gets an area in 
virtual storage to generate 
the access method control 
block and returns the 
address in register 1. 
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GET 


BNZ 


GENCB 


LTR 
BNZ 


LOOP MVC 
GET 
LTR 


BNZ 
SHOWCB 


LTR 
BNZ 


ERROR 


CHECKO ... 
RCDADDR DS 


SRCHKEY DS 
RCDLEN DS 


CHECKO 

2,1 

BLK=RPL, 
ACB=(2), 
AREA=RCDADDR, 
AREALEN=4, 
ARG=SRCHKEY, 
OPTCD=(KEY, SKP, 
SYN, NUP, KGE, 
FKS , LOC) 
15,15 

CHECKO 


3,1 


SRCHKEY, source 


RPL=(3) 

15,15 

ERROR 
AREA=RCDLEN, 
FIELDS=RECLEN, 
LENGTH=4, 
RPL=(3) 

15,15 


CHECKO 


LOOP 


CL8 


Address of the request 
parameter list. 


Search argument for 
retrieval, moved in from 
a table or a transaction 
record. 


Display the length of the 
record. 


Request was not accepted, 
or failed. 


Generation or display 
failed. 


Work area into which VSAM puts 
the address of a data record 
within the I/O buffer 
(OPTCD=LOC). 


Search argument for retrieval. 


For displaying variable record 
lengths. 


The macros and instructions are as follows: 
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GET 


e The first GENCB generates an access method control block, which specifies 
keyed, skip-sequential, and input processing. The address of the access 
method control block is stored in register 2. 


© The second GENCB generates a request parameter list. The address of the 
request parameter list is stored in register 3. 


@ MVC moves the search argument into SRCHKEY, the area defined for the 


search argument. 


© GET specifies that the record pointed at by the request parameter list whose 
address is in register 3 is to be retrieved. Records are retrieved by a 
skip-sequential search through the sequence set of the index. 


Example 4: Addressed-Sequential Retrieval 


In this example, one GET macro is used to retrieve multiple fixed-length, 20-byte 
records. The records are moved to a work area (only option). 


BLOCK ACB  DDNAME=INPUT, 
MACRF=(ADR, SEQ, 


: IN) 

GENCB BLK=RPL, 
COPIES=10, 
ACB=BLOCK, 
OPTCD=(ADR, SEQ, 
SYN, NUP, MVE) 

LTR =—-:15,15 

BNZ  CHECKO 

LA 3,10 

LR 2,1 

LR 1,0 

SR 0,0 

DR 0,3 

LR 3,1 

LR 4,2 

LA 5 ,RECAREA 

Chapter 2. 


Number of lists(10). 
Address of the first list. 


Length of all of the lists. 
Registers 0 and 1 contain 
length and address of the 
generated control blocks 

when VSAM returns control 
after GENCB. 

Prepare for following division. 


Divide number of lists into 
length of all the lists. 


Save the resulting length of a 
single list for an offset. 


Save address of the first 
list. 

Address of the first work 
area. 

Do the following 6 
instructions 10 times to set 
up all the request parameters 
lists. The 10th time, register 
4 must be set to 0 to indicate 
the last request parameter 
list in the chain. 
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MODCB 


LTR 
BNZ 


LOOP GET 
LTR 
BNZ 


CHECKS 
ERROR... 


RECAREA DS 


4,3 
RPL=(2), 
NXTRPL=(4), 
AREA=(5), 
AREALEN=20 
15,15 
CHECKO 

2,3 


5,20(5) 


RPL=( 2) 
15,15 
ERROR 


LOOP 


CL200 


Address the next list. 


In each request parameter list, 
indicate the address of the 
next list and the address and 
length of the work area. 


Address the next list. 


Address the next work area. 

Restore register 2 to address 
the first list before continuing 
to vrocess. 


Process the 10 records that 
have been retrieved by the 
GET. 


Display the feedback field 
(FIELDS=FDBK) of each request 
parameter list to find out 
which one had an error. 


Space for a work area for each 
of the 10 request parameter 
lists. 


The GENCB macro generates 10 request parameter lists; the lists are 
subsequently chained together by using the MODCB macro to modify the 
NXTRPL parameter in each copy. Because SEQ is specificd in each request 
parameter list and no previous request has been issued against the access method 
control block since it was opened, retrieval begins at the beginning of the data set. 
Each time the GET macro is executed, VSAM is positioned at the next record in 
RBA sequence. VSAM moves each record into the work area provided for the 
request parameter list that identifies the record. 


If an error occurred for one of the request parameter lists in the chain and you 
have supplied error-analysis routines, VSAM takes a LERAD or SYNAD exit 
before returning to your program. Register 15 is set to indicate the status of the 
request. A code of 0 indicates that no error was associated with any of the 
request parameter lists. Any other code indicates that an error occurred for one 
of the request parameter lists. You should issue a SHOWCB macro for each 
request parameter list in the chain to find out which had an error. VSAM 
doesn’t process any of the request parameter lists except the one with an error. 
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Example 5: Sequential Retrieval for a Relative Record Data Set 


GET 


In this example, a GET macro is used to sequentially retrieve records by relative 
record number. Fixed-length, 100-byte records are moved to a work area. 
Processing is synchronous. 


INPUT ACB 


RETRVE RPL 
LOOP GET 
LTR 
BNZ 
B 
ERROR eit 
IN DS 


RCDNO DS 


MACRF=(KEY, SEQ, 
IN) —— 


ACB=INPUT, 


OPTCD=(KEY , SEQ, 
SNY, NUP, MVE) 
—,, 


RPL=RETRVE 


15,15 
ERROR 


LOOP 


CL100 


CL4 


All MACRF and OPTCD 
subparameters specified are 
defaults and could have been 
omitted. 


This GET or identical GETs 

can be issued, with no change 
in the RPL, to retrieve 
subsequent records in relative 
record number sequence. 


Request was not accepted or 
it failed. 


IN contains a data record 
after GET is completed. 


VSAM returns relative record 
number of retrieved record in 
this field. 


The records arc retrieved in relative record number sequence. Empty records are 
bypassed for sequential retrieval. A 4-byte search argument must be spcecificd. 
The relative record number of each record retrieved is stored in the search 
argument. VSAM is positioncd at the first relative record whcn the data sct is 
opened, and the next nonempty record is retrieved automatically as cach GET is 
issucd. The branch to ERROR would also be taken if the end of the data sct 1s 


reached. 
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Example 6: Keyed-Direct Retrieval 


In this example, a GET macro is used to retrieve fixed-length, 100-byte records 
directly by key. The key length is 15 bytes; the search argument is a 5-byte 
generic key, compared equal. The control blocks are generated at assembly. 


INPUT ACB 
RETRVE RPL 
LOOP MVC 
GET 
LTK 
BNZ 
B 
ERROR. 
IN _ DS 
KEYAREA DS 


MACRF=(KEY, 
D N) 


3 


ACB=INPUT, 


DIR,SYN,NUP, 
KEQ,GEN, LOC), 
ARG=KEYAREA, 
KEYLEN=5 


KEYAREA, SOURCE 
RPL=RETRVE 


15,15 
ERROR 


LOOP 


CL4 


CL5 


You specify all parameters for 
the request in the RPL macro. 


Search argument for retrieval, 
moved in from a table or a 
transaction record. 


This GET or identical GETs can 
be issued with no change in the 
RPL: Specify each new search 
argument in the field KEYAREA. 


Process the record. 


Request was not accepted, or 
failed. 


VSAM puts here the address of 
the record within the I/0 
buffer. 


You specify the search argument 
here. 


The generic key specifics a class of records. For example, if you scarch on the 
first third of employee number, VSAM positions at and retrieves the first of 
presumably several records that start with the specified characters. To retrieve all 
the records in that class, either switch to sequential access or to a full-key search 


with a greater-than-or-cqual comparison. 
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Example 7: Addressed-Direct Retrieval 


GET 


In this example, a GET macro is used to retrieve fixed-length 20-byte records. 
The records are to be moved to a work area. 


BLOCK ACB 
GENCB 
LTR 
BNZ 
LR 

LOOP MVC 
GET 
LTR 
BNZ 
B 

CHECKO 

ERROR ees 

IN DS 

SRCHADR ODS 


DDNAME=INPUT , 


MACRF=(ADR, DIR, 


IN) 


BLK=RPL, 
COPIES=1, 
ACB=BLOCK, 


OPTCD=(ADR, DIR, 


SYN, NUP, MVE) 
15,15 

CHECKO 

2,4 


SRCHADR, 


RPL=(2) 


15, 15 
ERROR 


LOOP 


CL20 


CL4 


Access method control 
block generated at 
assembly. 


ARG=SRCHADR, AREA=IN, 
AREALEN=20 

Request parameter list 
generated at execution. 


Address of the list. 


Search argument for 
retrieval; calculated or 
moved in from a table or 
a transaction record. 


Process the record. 


Generation failed. 


Request was not accepted, 
or failed. 


VSAM puts a record here 
for each GET request. 


You specify the RBA 
search argument here for 
each request. 


The RBA provided for a search argument must match the RBA of a record. 
Keyed insertion and delction of records in a key-sequenced data set will probably 
cause the RBAs of some records to change. Therefore, if you process a 
key-sequenced data set by addressed-direct access (or by addressed-sequential 
access using POINT), you need to keep track of changes. You can use the 
JRNAD exit for this purpose. See “EXLST Macro (Generate an Exit List at 
Assembly Time)” on page 66. 
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“eo 


Example 8: Switch from Direct to Sequential Retrieval 


In this example, GET macros are used to retrieve fixed-length, 100-byte records. 
The retrieval is via an alternate index path defined with the nonunique key 
option. Every time a nonunique key is retrieved, the program switches to 
sequential processing to retrieve the other records with the same key. The 
control blocks were generated at assembly, but the MODCB macro is used to 
modify the request parameter list to permit switching from kcyed-dircct to 
keyed-sequential retrieval. For the direct request preceding sequential requests, 


the search argument is an 8-byte, gencric ke 
requested for direct requests. 


INPUT ACB 


RETRVE RPL 


M¥e 


LOOP1 GET 
LTR 


BNZ 
SHOWCB 


LTR 
BNZ 
CLI 


BE 


SEQ MODCB 


LTR 
BNZ 


MACRF=(KEY, DIR, 
SEQ, IN) 


ACB=INPUT, 
AREA=IN, 
AREALEN=100, 
OPTCD=(KEY, DIR, 
SYN,NSP, KEQ, 
GEN,MVE), 
ARG=KEYAREA, 
KEYLEN=€ 


KE¥AREA, source 


RPL=RETRVE 
15,15 
ERROR 


RPL=RETRVE, 
AREA=FDBAREA, 
FIELDS=FDBK 
15,15 

ERROR 


ERRCD, 8 
SEQ 
LOOP 


RPL=RETRVE, 
OPTCD=SEQ 


15,15 
CHECKO 
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y, compared equal. Positioning is 


Both direct and 
sequential access 
specified. 


NSP specifies that VSAM 
is to remember its 
position. 


Search argument for 
direct retrieval; moved 
in from a table or a 
transaction record. 


Extract feedback 
information. 


Does a duplicate key 
follow? 


Yes; retrieve duplicates 
sequentially. 


No; retrieve next record 
in direct mode. 


Alter request parameter 
list for sequential 
access. 


SEQGET 


DIR 


ERROR 


CHECKG 


IN 


KEYAREA 


FDBAREA 


TYPECD 


CMPCD 
ERRCD 


GET 
LTR 
BNZ 


SHOWCB 


LTR 
BNZ 
CLI 


BE 
MODCB 


LTR 
BNZ 


DS 
DS 


DS 
DS 
DS 
DS 
DS 


RPL=RETRVE 
15,15 
ERROR 


RPL=RETRVE , 


AREA=FDBAREA, 


FIELDS=FDBK 
15,15 

ERROR 
ERRCD, 8 
SEQGET 
RPL=RETRVE, 
OPTCD=DIR 
15,15 
CHECKO 
LOOP 


CL100 


CL8 


OF 
1C 
1C 
1C 
1C 


GET 


Do sequential retrieval. 


Test for error. — 


Extract feedback 
information. 


Does a duplicate key 
follow? 


Yes; retrieve 
sequentially. 


Alter request parameter 
list for direct access. — 


Prepare new search 
argument. 


Request was not accepted, 
or failed. 


Modification failed. 


VSAM puts retrieved 
records here. 


Specify the generic key 
for a direct request 
here. 

Feedback area for SHOWCB. 
Reserved. 

Error type code. 


Component code. 


Reason code. 


Positioning is associated with a request parameter list; the MODCB macro is 
used to modify a single request parameter list that alternately defines requests for 
both types of access rather than use a different request parameter list for each 


type. 


With direct retrieval, VSAM doesn’t remember its position for subsequent 
sequential retrieval unless you explicitly request it (OPTCD = NSP or UPD). 
After a direct GET for update, VSAM is positioned for a subsequent PUT, 
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ERASE, or sequential GET. If you modify OPTCD=(DIR,NUP) to 
OPTCD=SEQ, you must issue POINT to get VSAM positioned for sequential 
retrieval, as NUP indicates that no positioning is desired with a direct GET. 


If you have chained many request parameter lists together, one position is 
remembered for the whole chain. For example, if you issue a GET that gives the 
address of the first request parameter list in the chain, the position of VSAM 
when the GET request is complete is at the record following the record defined 
by the last request parameter list in the chain. Therefore, modifying 
OPTCD=(DIR,NSP) in each request parameter list in a chain to 

OPTCD= SEQ implies continuing with sequential access relative to the last of 
the direct request parameter lists. 
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GETIX 


GETIX Macro (Retrieve an Index Record) 


The format of the GETIX macro is: 


[labe]] GETIX | RPL= address 


where: 


label 
is 1 to 8 characters that provide a symbolic address for the GETIX macro. 


RPL = address 
specifies the address of the request parameter list that defincs this GETIX 
request. You may specify the address in register notation (using a register 
from I through 12, enclosed in parentheses) or specify it with an expression 
that gencrates a valid relocatable A-type address constant. 


The following RPL parameters and subparameters are required for GETIX: 


OPTCD = (CNV 
,DIR 
,(NUP|UPD|NSP} 
,(LOC|MVE}) 


GETIX can be issued either for update or not for update; 
OPTCD= NSP 1s interpreted as OPTCD= NUP. 


With OPTCD= MVE, AREALEN must be at Icast index control 
interval size. 


ARG = address 
The search argument for GETIX is the RBA of a control interval. 


To process the index of a key-sequenced data set with GETIX, you must open 
the cluster with: 


ACB MACRF=(CNV,...) 
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MNTACQ Macro (Mount Acquire) 
The format of the MNTACQ macro is: 


[/abef{ RPL = address 


RPL = address 
specifies the address of the RPL that identifics your opencd VSAM data set 
and your arguments. The following RPL parameters have meaning for 
MNTACQ: 


ACB = address 
identifies your VSAM data set. 


ARG = address 


identifies your arguments. address points to a paramcter list, aligned 
on a fullword boundary as follows: 


Offset Length Contents 


0 4 Feedback area: address of an 
ECB WAIT list 

4 6 VOLSER, target volume 

10 l Reserved 

ll 1 Argument entry count (N) 
(N = I to 255) 

12  4N Argument entries 

12+ 4(N-1) 4 RBA for which an ACQUIRE is 
requested ; 


The maximum number of arguments is 255. 


For the specificd list, MNTACQ will acquire (stage) the data cylinders 
corresponding to each RBA for the one given volume. The volume 
will be mounted if necessary. 


OPTCD =({ADR|KEY} 
,(ASY[SYN} 
{KEQ|KGE} 
.FKS) 


ADR is valid for entry-sequenced data set, error for key-sequenced 
data set or relative record data set. 


98 MVS/XA VSAM Administration: Macro Instruction Reference 


MNTACQ 


KEY is valid for key-sequenced data set and relative record data set, 
- error for entry-sequenced data set. 


If ASY is specified, you cannot WAIT on the RPLECB field for 
MNTACQ or ACQRANGE. You use the address placed in the 
parameter list feedback area. This address points to a list of ECBs (in 
standard WAIT list format) which you may use in place of the 
RPLECB field. 


GEN is not supported; if specified, it will give an error indication. 


All other OPTCD parameters are not applicable, and, if specified, are 
ignored with no error indication. 


Because your request may result in the staging of numcrous cylinders, a single 
ECB is not sufficient for an asynchronous MNTACQ request. The RPLECB 
ficld is inoperative for the MNTACQ interface. Upon return from an 
asynchronous MNTACQ, the fecdback area of the MNTACQ parameter list will 
contain the address of a standard ECB WAIT list. You must then use this list in 
conjunction with the WAIT macro or you may use the list in conjunction with 
the EVENTS macro of MVS. An asynchronous request must conclude with 
either CHECK, ENDREQ, or CLOSE. 


At the conclusion of this macro, the RPL is disconnected in a manner similar to 
that of a direct VSAM request. Any positioning in effect prior to execution of 
this macro will be lost. You may have to reposition. Chained RPLs are not 
supported by MNTACQ. 
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MODCB Macro (Modify an Access Method Control Block) 


The format of the MODCB macro used to modify an access method control 
block is: 





[label] MODCB} ACB= address 
[BSTRNO = number] 
{,BUFND = number] 
[,BUFNI = number} 
|,BUFSP = number} 
[,CATALOG = YES|NO] 
[,CRA = SCRA|UCRA]J 
[,.DDNAME = ddname} 
[,EXLST = address] 
| MACRF = ((ADR][,CNV][, KEY] 
[,CFX|NFX] 
[|,DDN|DSN] 
{,.DFRINDF] 
[,DIR]LSEQ],SKP] 
[ ICIINCH 
[IN],OUT] 
[,NIS|SIS} 
[, NRM[AIX] 
LNRS|IRSTI 
[,NSR|LSR|GSR] 
|, NUB|UBF)] 
|, WEAREA = address] 
[, NILEN = number] 
[|,PASSWD = address] 
LE RMODE31 = {ALL|BUFF|CB|NONE}| 
{ SHRPOOL = number} 
|, STRNO = number} 


Note: The RMODE31 parameter replaces the AMODE31 subparameter shown 
in previous releases. 


The parameters of the MODCB macro can be expressed as absolute numeric 
expressions, as character strings, as codes, as expressions that generate valid 
rclocatable A-type address constants, in register notation, as S-type address 
constants, and as indirect S-type address constants. Appendix C, “Operand 
Notation” on page 181, further defines these operand expressions. 


label 
is | to 8 characters that provide a symbolic address for the MODCB macro. 


ACB = address 
specifies the address of the access mcthod control block to be modified. 
The data set identified by the access method control block must not be 
opened. A request to modify the access method control block of an open 
data set will fail. 
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Note: The remaining parameters represent parameters of the ACB macro that 
can be modified. The value specified replaces the value, if any, presently in the 
access method control block. There are no defaults. For an explanation of these 
parameters, see “ACB Macro (Generate an Access Method Control Block at 
Assembly Time)” on page 34. 


If MODCB is used to modify a MACRF subparameter, other subparameters are 
unaffected, except when they are mutually exclusive. For example, if you specify 
MACRF= ADR in the MODCB and MACRF = KEY 1s already indicated in the 
control block, both ADR and KEY will now be indicated. But, if you specify 
MACRF = UBF in the MODCB and NUB 1s indicated, only UBF will now be 
indicated. 


The RMODE3]! parameter tells the VSAM OPEN routines where to obtain 
storage for the control blocks and I/O buffers. Therefore, the only time the 
values specified by the RMODE31 parameter have any effect on VSAM is on the 
setting just before an OPEN is issued. At other times, changing these values has 
no effect on the residency of the control blocks and I/O buffers. 


If MODCB RPL is used to change the address of an ACB, you must first issue 
an ENDREQ macro. 


Example: MODCB Macro (Modify an Access Method Control Block) 


In this example, a MODCB macro 1s used to modify the name of the exit list in 
an access method control block. 


MODCB ACB=BLOCK, BLOCK was generated at 
EXLST=EGRESS assembly. 
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MODCB Macro (Modify an Exit List) 


The format of the MODCB macro used to modify an exit list is: 


[/abel] MODCB | EXLST = address 
| |, EODAD = ({addressif,AINILLDI 


[, JRNAD = ({address}f, A|NILLD} 
[,LERAD = (faddress]], A|N][,L)] 
LSYNAD = (faddress]f,A|NILLD| 





The subparameters of the MODCB macro can be expressed as absolute numeric 
expressions, as character strings, as codes, as expressions that gencrate valid 
relocatable A-type address constants, in register notation, as S-type address 
constants, and as indirect S-type address constants. Appendix C, “Operand 
Notation” on page 181, further defines these operand expressions. 


Note: See Data Facility Product: Customization for the factors that determine 
the addressing mode and the parameter list residency mode set when the exit 
routine gets control. 


label 
is 1 to 8 characters that provide a symbolic address for the MODCB macro. 


EXESF = address 
specifies the address of the exit list to be modified. You can modify an exit 
list at any time—that is, before or after opening the data set(s) for which the 
list indicates exit routines. Ycu cannot, however, add an entry to the exit 
list if it will change the exit list’s length; the cxit list must already be large 
enough to contain the new exit address. The order in which addresses are 
stored in the EXLST control block is;)s EODAD, SYNAD, LERAD, 
JRNAD, and UPAD. For example, if you generate an exit list with only 
the LERAD exit, you can add entries for EODAD and SYNAD later; you 
cannot add the JRNAD exit address, because doing so would increase the 
size of the EXLST control block. The MODCB macro does not support 
the UPAD user exit. 


Note: If the JRNAD exit is changed for an OPEN ACB, then the ACB 
must be closed and reopencd in order to use the modified JRNAD exit. 


For more information about user exit routines sce Data Facility Product: 
Customization. 


The remaining parameters represent parameters of the EXLST macro that can be 


modified or added to an exit list. For an explanation of these parameters, see 
“EXLST Macro (Gencrate an Exit List at Assembly Time)” on page 66. 
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MODCB—EXLST 


Example: MODCB Macro (Modify an Exit List) 


_ In this example, a MODCB macro is used to activate an exit in an exit list. 


MODCB EXLST=(* Indirect notation is used 
EXLSTADR), to specify the address of 
EODAD=(EOD,L,A) the exit list, which was 

generated at execution. 


EOD DC C'ENDUP' 
EXLSTADR DS F . When the exit list was 


generated, its address was 
saved here. 


The MODCB macro’s parameters are: 


e EXLST specifics that the address of the exit list to be modified is located at 
EXLSTADR. 


e EODAD spccifies that the entry for the end-of-data routine is to be marked 


active in the exit list whose address resides at EXLSTADR. The namc of the 
end-of-data routinc, ENDUP, is located at EOD. 


Chapter 2. VSAM Macro Formats and Examples 103 


MODCB—RPL 


MODCB Macro (Modify a Request Parameter List) 


The format of a MODCB macro used to modify a request parameter list is: 


[abe =| MODCB| RPL= address 

{, ACB = address] 

[, AREA = address| 

{, AREALEN = nwnber} 

L.ARG = address} 

[,ECB = address] 

|, KEYLEN = number} 

{, MSGAREA = address] 

|, MSGLEN = awnber} 

|, NXTRPL = address] 

{,OPTCD = ((ADR|CNV|KEY] 
|, DIR|SEQ|SKP] 
[, ARD|LRD] 
[,.FWD|BWD] 
[L,ASY|SYN] 
[,.NSP|NUP|UPD] 
.KEQ|KGE] 
|. FKS|GEN] 
|, LOC|MVED}] 

jp RECTEN = number{ 

[,.TRANSID = number} 





The parameters of the MODCB macro can be expressed as absolute numeric 
expressions, as character strings, as codes, as expressions that generate valid 
relocatable A-type address constants, in register notation, as S-type address 
constants, and as indirect S-type address constants. Appendix C, “Operand 
Notation” on page 181, further defines these operand expressions. 


label 
is | to 8 characters that provide a symbolic address for the MODCB macro. 


RPL = address 
specifies the address of the request parameter list to be modified. You may 
not modify an active request parameter list; that is, one that defines a 
request that has been issued but not completed. To modify such a request 
parameter list, you must first issue a CHECK or an ENDREQ macro. 


Note: The remaining parameters represent parameters of the RPL macro that 
can be modified. The value specificd replaces the value, if any, presently in the 
request parameter list. There are no defaults. For an explanation of these 
parameters, sce “GENCB Macro (Gencrate a Request Parameter List at 
Execution Time)” on page 80. 


If MODCB is used to modify an OPTCD subparameter within a group of 
subparameters, the current subparameter for that group is changed, because only 
one subparameter in a group is effective at a time. Only the OPTCD 
subparameter specified is changed; all other OPTCD subparameters remain 
unchanged. 
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MODCB—RPL 


Example: MODCB Macro (Modify a Request Parameter List) 


In this example, a MODCB macro is used to modify the record length field in a 
request parameter list. 


Note: This example also shows the one exception to GENCB, MODCB, 
SHOWCEB, and TESTCB building a parameter list and passing it to the control 
block manipulation module in register 1. In this example, the RPL address (in 
register 2) would be loaded into register 1 and the RECLEN value (in register 3) 
would be loaded into register 0. These registers would be passed to the control 
block manipulation macro. This will occur if the LIST, EXECUTE, or 
GENERATE form of the MODCB macro is not used and the only paramcter 
specified, besides RPL, is RECLEN. 


L 3, length Load the new record length. 


MODCB RPL=(2), Register 2 contains the address 
of the request parameter list. 


RECLEN=(3) Register 3 contains the record 
. length. 


The MODCB macro’s parameters are: 


e RPL specifies that register 2 contains the address of the request paramctcr list 
to be modified. 


© RECLEN specifies that the record length field is to be modified. The 
contents of register 3 will replace any current value in the RECLEN ficld. 
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MRKBFR 


“e 


MRKBER Macro (Mark Buffer) 


The format of the MRKBFR macro is: 


MRKBFR 





MARK = {DINVALID|XINVALID|OUT|RLS} 
specifies whether to mark for output or to release from exclusive control or 
shared status the buffer identified in the RPL. To do both, issue 
MRKBER twice, once with MARK = OUT, again with MARK=RLS. 


DINVALID|XINVALID . 
specifies whether to mark the data component or index component 
buffers invalid. The buffers to be invalidated are identified as those 
which contain records, whose RBA values are within the RBA range 
pointed to by the RPL ARG address. DINVALID specifies that the 
data component buffers are to be marked invalid; XINVALID 
specifies that the index component buffers are to be marked invalid. 


OUT - 
indicates that the buffer is to be marked for output. The buffer is 
kept under exclusive control or in shared status. 


RLS 
indicates that the buffer is to be released from exclusive control or 
shared status. 


RPL = address 
specifies the address of the request parameter list that defines the 
MRKBER request. Use the RPL used by SCIIBFR or GET to locate the - 
buffcr being marked or released. These RPL parameters have meaning for 
MRKBER: 


ACB = address 
ARG = address 
The address of the 8-byte ficld that contains the beginning and ending 


RBAs of the range to be scarched on. 


ECB = address 


TRANSID = number 


All other RPL parameters are ignored. RPLs are assumed not to be 
chained. OPTCD=LOC is assumed. . 


If the ACB to which the RPL is related has MACRF=GSR, the 


program that issues MRKBFR must be in supervisor state with 
protection key 0 to 7. 
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OPEN 


| OPEN Macro (Connect Program and Data) 


eee eee eee die 


The format of the OPEN macro is: 





label 
is 1 to 8 characters that provide a symbolic address for the OPEN macro. 


address 
specifics the address of the ACB or DCB for the data sct(s) to be opencd. 
You may specify the addrcss in register notation (using a register from 2 
through 12, in parentheses) or specify it with an expression that gencrates a 
valid relocatable A-type address constant. If you usc register notation to 
open only one data sect, you must enclose the expression identifying the 
registcr in two sets of parentheses: for example, OPEN ((2)). 


options 
arc options paramctcrs for use only in opening non-VSAM data sets. If 
any options are specificd with the address of an access method control 
block, VSAM ignores them. 


MODE = 
specifies the format of the OPEN parameter list that 1s to be gencrated. 


24 
specifies that a standard form (24-bit) parameter list address is to be 
gencrated. The parameter list must reside below 16 megabytes and 
point to an ACB residing below 16 megabytes. ‘This is the default 
paramcter. . 


31 
specifies that a long form (31-bit) parameter list address is to be 
generated. This paramcter value must be coded if the paramcter list 
or the VSAM/VTAM ACB resides above 16 megabytes. 


Note: If the VSAM control blocks and buffers are to reside above 16 megabytes, 
the RMODE3! parameter must be specificd in the ACB before the OPEN is 
issucd. 


Because the OPEN parameters are positional, include a comma for options (even 
if you don’t specify options) before a subsequent parameter. 
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OPEN 


Example 1: OPEN Macro used to open two data sets. 


In this example, the access method control block for one data set was generated 
at execution; the other was generated at assembly. 


GENCB BLK=ACB, An access method control block. 
DDNAME=DATA 

LTR 15,15 

BNZ ERROR 

LR 2,1 Address of the control block. 


OPEN (BLOCK,,(2)) A label is used for the access 
method control block generated 
by ACB; register notation is used 
for the one generated by GENCB. 
The two commas indicate the 
omission of options. 


BLOCK ACB Another access method control 
block. 


| Example 2; OPEN Macro with a parameter list above 16 megabytes. 


| | | This example shows a program being opened with a parameter list that may 
| reside above 16 mcgabytes. 


OPLSTA OPEN MODE=31, 
MF=(E, OPLSTB) 


OPLSTB OPEN’ (ACB1,,ACB2), 
MODE=31, 
MF=L 


on) coe 


| Since MODE = 31 is coded in the list form of the OPEN macro, VSAM ACBs 
| and the OPEN parameter list may reside above 16 megabytes. 


Note: Consistency must be maintained while using the MODE operand in the 
MF=L and MF=E versions of the OPEN macro. If MODE=31 is specified in 
the MF=L version, then MODE = 31 must also be coded in the corresponding 
MF=E version of the macro. Unpredictable results may occur if this rule is not 
followed. 


| MF=E and MF =L are not required. OPEN (ACB1), MODE =31 1s also valid. 
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POINT 


POINT Macro (Position for Access) 


The format of the POINT macro is: 


{label} POINT | RPL= address 


label 
is | to 8 characters that provide a symbolic address for the POINT macro. 


RPL = address 
specifies the address of the request parameter list that defines the request. 
You may specify the address in register notation (using a register from 1 
through 12, enclosed in parentheses) or specify it with an expression that 
generates a valid relocatable A-type address constant. 


Example: Position with POINT 


In this example, the POINT macro is used to position at a record identified by a 
full key (5-byte) scarch argument, compared equal. 
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POINT 


BLOCK ACB DDNAME=I0 Default MACRF subparameters 
| sufficient. 
POSITION RPL ACB=BLOCK, ARG parameter and KEQ and 
AREA=WORK, FKS OPTCD subparameters 
AREALEN=50, define the POINT request. 
ARG=SRCHKEY, 
OPTCD=(KEY, SEQ, SYN, KEQ, FKS) 
LOOP MVC SRCHKEY, source Search argument for 
positioning, moved in from 
POINT RPL=POSITION a table or a transaction 
record. j 
LTR 15,15 
BNZ ERROR 
LOOP1 GET RPL=POSITION 
LTR 15,15 
BNZ ERROR 


Process the record. Decide whether to skip to another 
position (forward or backward). 


BE LOOP Yes; skip. 
B LOOP1 No; continue in 
consecutive sequence. 
ERROR sake Request was not accepted, 
‘ or failed. 
SRCHKEY DS CLS Search argument for 
positioning. 
WORK DS CLS50 VSAM puts a record here 


for each GET request. 
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PUT 


PUT Macro (Store a Record) 


The format of the PUT macro is: 


[/abeq] RPL = address 


label 
is 1 to 8 characters that provide a symbolic address for the PUT macro. 


RPL = address 
specifics the address of the request parameter list that defines the request. 
You may specify the address in register notation (using a register from | 
through 12, enclosed in parentheses) or specify it with an expression that 
generates a valid relocatable A-type address constant. 


Note: If the PUT macro is being used to load records into an empty data sct, 
the STRNO value in the access method control block must be 1, and RPL 
OPTCD= DIR must not be specified. However, for an empty relative record 
data sect, DIR is allowed. 


Example 1: Keyed-Scquential Insertion 


In this example, a PUT macro is used to perform keyed-sequcntial insertion. 
Variable-length records with a key length of 15 bytes are to be moved from a 
work area. Some records will be inserted between existing records; other records 
will be added at the end of the data set. 
BLOCK ACB DDNAME=OUTPUT, 

MACRF=( KEY, SEQ, OUT) 


LIST RPL § ACB=BLOCK, 
AREA=BUILDRCD, 
AREALEN=250, 
OPTDC=(KEY, SEQ, 


SYN, NUP, MVE) 

LOOP L 2,source Put length of record to 
be inserted into. 
register. 

MODCB RPL=LIST, Indicate record length 
RECLEN=( 2) in request parameter 
list. 
LTR 15,15 
BNZ CHECKO 
PUT RPL=LIST 
LTR 15,15 
BNZ ERROR 
B LOOP 
CHECKO ae Modification failed. 
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PUT 
ERROR... 


BUILDRCD DS 


CL250 


Request was not accepted, 
or failed. 


Work area for building 
records. 


The request parameter list, LIST, is associated with the access method control 
block, BLOCK. The length of cach record to be inserted is put into register 2, 
which is subsequently used by MODCB to change the record length in the 
request parameter list. The record length is, therefore, correctly indicated in the 
request parameter list before the PUT macro is issued. The execution of the 
PUT macro causes VSAM to skip ahead (never back) to the next record. 


Example 2: Recording RBAs When Loading 


In this example, a PUT macro is used to record the RBAs of records as they are 
loaded into a key-sequenced data set. The RBAs are recorded in a table with 
20-byte entnes (4 bytes for RBA, 15 bytes for associated key, and | byte of 
padding so the next entry begins on a fullword boundary). 


LA 
LOOP L 


MODCB 


LTR 
BNZ 
PUT. 
LTR 
BNZ 
SHOWCB 


LTR 
BNZ 
MVC 


ERROR 
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3, RBATABLE 


2,source 
RPL=LIST, 
RECLEN=( 2} 
15,15 
CHECKO 
RPL=LIST 
15,15 
ERROR 
AREA=(3), 
FIELDS=RBA, 
LENGTH=4, 
RPL=LIST 
15,15 
CHECKO 


4(15,3), 
keyfield 


3,20(3) 
LOOP 


Address of the beginning of 
the table. 


Put length of record to be 
inserted into register 2. 


Indicate record length in 
request parameter list. 


Each SHOWCB puts a record's 
RBA into the table. 


Put the record's key field 
in the table. 


Point to the next entry. 


Request was not accepted, 
or failed. 


PUT 


CHECKO... Modification or display 
: failed. 
DSECT Get enough virtual storage 


for as many table entries 
as there are records in 
the data set. 

RBATABLE DS OF 


RBA DS CL4 
KEY DS CL15 
DS CL1 Padding to keep each RBA 


entry on a fullword 
boundary: SHOWCB's display 
area must be on a fullword 
boundary. 


The necd to process a key-sequenced data set by address should be unusual, but 
by recording the RBA of each record in a key-sequenced data set, you have 
search arguments for possible processing of the data set by addresscd-direct 
retrieval and by addressed-scquential retrieval using the POINT macro. (You 
don’t need to know RBAs to process a key-sequenced data set by simple 
addressed-sequential retneval, since you go from the beginning without any 
skips.) 


You can display the RBA of a record after you issue a GET or a POINT, as well 
as after you issue a PUT. 


Example 3: Loading a Relative Record Data Set (Skip-Scquential and Direct Processing) 


In this example, a PUT macro is used to store twenty 100-byte records in slots 5, 
10, 15,...,100 of the data sect. MODCB is used to switch to direct processing, and 
a PUT 1s used to store records in slots 26 and 51 of the data set. 


OUTACB ACB MACRF=(SKP, OUT, 


DIR, KEY) 

GENCB BLK=RPL, Generate a request 
ACB=OUTACB, parameter list at 
AREA=WORK, execution time. 
AREALEN=100, 

ARG=RCDNO, 
OPTCD=(KEY, SKP) 

LTR 15,15 

BNZ.. GENFAIL 

LR 5,0 Save length of RPL. 

LR 6,1 Save address of RPL. 

LA 7,5 Initialize increment 

value. 

ST 7,RCDNO Initialize argument to 

slot 5. 
LA 10,20 Initialize loop counter. 
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PUT 


LOOP 


GENFAIL 
PUTERR 
RETURN 


WORK 


RCDNO 
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PUT 
LTR 
BNZ 


ST 
BCT 
MODCB 


LTR 
BNZ 


ST 


PUT 
LTR 
BNZ 


ST 


PUT 
LTR 
BNZ 


DS 


DS 


RPL=(6) 
15,15° 
PUTERR 
1,RCDNO 
1,7 
1,RCDNO 
10, LOOP 
RPL=(6) 


OPTCD=(DIR, KEY) 


15,15 
GENFAIL 
7,51 
7,RCDNO 


RPL=(6) 
15,15 
PUTERR 
7,26 
7,RCDNC 


RPL=(6) 
15,15 
PUTERR 


RETURN 


CL100 


CL4 


Move new record into work. 


Store record. 


Request was not accepted, 
or failed. 


Increment argument by 5. 


Switch to direct processing 
to store records in slots 
51 and 26. 


Initialize argument to slot 
51. 


Move new record into WORK. 


Store record in slot 51. 


Request was not accepted, 
or failed. 


Initialize argument to slot 
26. 
Move new record into WORK. 


Store record in slot 26. 


Request was not accepted, 
or failed. 


Generation or modification 
failed. 


PUT request was not 
accepted, or failed. 


Terminate program. 


100-byte work area that 
contains record to be 
stored by PUT macro. 


4-byte relative record 
number. 


PUT 


Both skip-sequential and direct processing can be used to create a relative record 
data set. The ACB is opened for output. The 4-byte search argument 
(RCDNO) indicates the slot number where the record is to be stored. 


Example 4: Keyed-Scquential Insertion (Relative Record Data Sct) 


In this example, a PUT macro is used to insert twenty 100-byte records into 
empty slots of a previously loaded relative record data set. If the slot is empty 
when the PUT is issucd, the record is stored and the slot number (returned in the 
argument field) is stored in a table. If the slot is not empty when the PUT is 
issucd, a duplicate record error indication is returned. When a duplicate record is 
indicated, the PUT is reissucd until the record is successfully stored in an empty 


slot in the data sect. 


OUTACB ACB 


GENCB 


LTR 
BNZ 


S 


WRITERCD ... 


PUT 
LTR 
BZ 


CLR 
BNE 
TESTCB 


BE 


MACRF=(KEY, SEQ, 
OUT) 


BLK=RPL, 
ACB=OUTACB, 
AREA=WORK, 
AREALEN=100, 
ARG=RCDNO, 
OPTDC=(KEY , SEQ) 
15,15 

GENERR 

6,1 


4,RRNTABLE+80 


3, RRNTABLE 


RPL=(6) 
15,15 
STRCDNO 
10,8 
10,15 
PUTERR 


RPL=(6) , FDBK=8, 
ERET=TESTERR 


WRITERCD 


PUTERR 
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Generate a request parameter 
list. 


Save the address of the RPL. 


Initialize address of end of 
table. 


Initialize index to relative 
record number table. 


Move record into work area. 


Branch, if PUT is successful. 
Test for logical error. 

Test for duplicate record. 
Branch, if duplicate record, 


and try to store record in 
next slot. 


115 


PUT 


STRDCNO Sie 
MVC. 0(4,3)RCDNO Store relative record 
number in RRNTABLE. 
LA 3,4(3) Increment to next table 
entry. 
CLR 3,4 
BE RETURN If table full, return to 
caller. 
B WRITERCD Write next record. 
GENERR ae Error routine for GENCB 
macro. 
TESTERR ... Error routine for TESTCB 
macro. 
PUTERR sae Error routine for PUT 
macro. 
RETURN ew Return to caller or 
terminate program. 
RCDNO DS CL4 4-byte relative record 
number (argument) field. 
RRNTABLE DS 20F Relative record number 
table. 
WORK DS CL100 100-byte work area that 


contains record to be 
stored by PUT macro. 


Each record is stored in the next available slot in the data set. When a record is 
successfully stored, its rclative record number is recordcd in a table. 


Example 5: Skip-Sequential Insertion 


In this example, one PUT macro is used to insert multiple fixed-length, 100-byte 
records. Records are to be moved asynchronously from a work area. 


OUTPUT ACB MACRF=(KEY, SKP, 
OUT) 


GENCB BLK=RPL, Generate 5 request 
COPIES=5, parameter lists at 
ACB=OUTPUT, execution. 
AREALEN=100, 

OPTCD=(KEY,SKP, 
ASY,NUP, MVE), 
RECLEN=100 


LTR 15,15 
BNZ CHECKO 
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PUT 


Calculate length of each list and use register notation with 
the MODCB macro to complete each list. 


MODCB RPI=(2), 
AREA=(3), 
NXTRPL=(4) 


LTR 15,15 
BNZ CHECKO 


Increase the value in each register and repeat the MODCB 
until all five request parameter lists have been completed. 
The last time, register 4 must be set to 0. 


LOOP a Restore address of first 
list in register 2. 
Build 5 records in WORK. 


PUT RPL=(2) Register 2 points to the 
first request parameter 
list in the chain. The 
five records in WORK are 
stored with this one 

LTR 15,15 PUT request. 


BNZ NOTACCEP 


CHECK RPL=(2) 


LTR 15,15 
BNZ ERRO 
B LOOP 
CHECKO bert Generation or modification 
failed. 
NOTACCEP 
ERROR eas Display the feedback field 
in each request parameter 
list to find out which one 
had an error. 
WORK DS CL500 Contains five 100-byte work 


areas. 


You give no search argument for storage: VSAM knows the position of the key 
ficld in cach record and extracts the key from it. Skip-sequential insertion differs 
from keyed-direct insertion in the sequence in which records may be inserted 
(ascending nonconsccutive sequence versus random sequence) and in 
performance. 


With skip-sequential insertion, if you insert two or more records into a control 
mterval, VSAM doesn’t write the contents of the buffer to direct-access storage 
until you have inserted all the records. With direct insertion, VSAM writes the 
contents of the buffer after you have inserted each record. 
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PUT 


Example 6: Keyed-Direct Insertion 


In this example, a PUT macro is used to move fixed-length, 100-byte records 
from a work area. 


OUTPUT ACB MACRF=(KEY, DIR, 
OUT) 

DIRECT RPL ACB=OUTPUT, 
AREA=WORK, 
AREALEN=100, 
OPTCD=( KEY, DIR, 
ASY,NUP,MVE), 
RECLEN=100 


LOOP PUT §RPL=DIRECT 
LTR 15,15 
BNZ  NOTACCEP 


CHECK RPL=DIRECT 


LTR 15,15 

BNZ ERROR 

B LOOP 
NOTACCEP ... Request was not accepted. 
ERROR ar Request failed. 
WORK DS CL100 Work area. 


The macros are as follows: 


e ACB specifies that the data set, OUTPUT, into which records are to -be 
inserted, is opened for kcyed-direct, output processing. 


e RPL spccifies that the record to be inserted into the OUTPUT data set 
resides in a 100-bytc area, WORK. 


VSAM extracts the key from the key field of each record found at WORK. 
Using keyed-direct access is similar to using skip-sequential access. 
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PUT 


Example 7: Addressed-Sequential Addition 


In this example, a PUT macro is used to add variable-length records to a data 
set. The data set is assumed to be an entry-sequenced data sct, because records 
cannot be inserted into or added to a key-sequenced data set with addressed 
access. 


BLOCK ACB MACRF=(ADR, SEQ, 
OUT) 


LIST RPL  ACB=BLOCK, 
AREA=NEWRCD, 
AREALEN=100, 


' OPTCD=(ADR, SEQ, 
SYN, MVE) 
LOOP fos Build the record. 
L 3,source Put the length of the 
record into register 3. 
MODCB RPL=LIST, Indicate length of new 
RECLEN=(3) record. 
LTR 15,15 


BNZ CHECKO 
PUT RPL=LIST 


LTR 15,15 

BNZ ERROR 

B LOOP 
CHECKO ... | Modification failed. 
ERROR eer Request was not accepted, 

or failed. 
NEWRCD DS CL100 so record in this work 
rea. 


Each record is stored in the next position after the last record in the data sct. 
You do not have to specify an RBA or do any explicit positioning (with the 
POINT macro). Addressed addition of records is always identical to loading a 
data sct: When additional space is required, VSAM extends the data sct. 


The only difference between addressed-sequential and addressed-direct addition is 
when the buffers are written to external storage. The buffer is written to external 
storage only when it is full for sequential addition; it is written after each record 
for direct addition. You cannot use direct storage to load records into a data set 
for the first time; you must use sequential storage. 
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Example 8: Keyed-Scquential Update 


In this example, GET and PUT macros are used to retrieve and update 
fixed-length, 50-byte records. Records are updated synchronously in a work area. 
This example requires the use of a work area because you cannot update a record 
in the I/O buffer. 


UPDATA ACB MACRF=( KEY, SEQ, 
OUT) 


LIST RPL ACB=UPDATA, UPD indicates the record may 
AREA=WORK, be stored back (or deleted). 
AREALEN=50, 
OPTCD=( KEY, SEQ, 
SYN, UPD, MVE) 


LOOP GET RPL=LIST 
LTR 15,15 
BNZ ERROR 


Decide whether to update the record. 
BE LOOP Do not update it; retrieve 


another. 


Do update the record. 


PUT RPL=LIST Store the record back. 
LTR 15,15 
BNZ ERROR 
B LOOP 
ERROR... Request was not accepted, or 
failed. 
WORK DS CL50 oe puts the retrieved record 
ere. 


A GET for update (OPTCD= UPD) must precede a PUT for update. Besides 
retricving the record to be updated, GET positions VSAM at the record retrieved, 
in anticipation of the succecding update (or deletion). It is not necessary for you 
to store back (or delete) the record that you retricved for update. VSAM’s 
position at the record previously retrieved allows you to issue another GET to 
retricve the following record. You cannot then, however, store back the previous 
record: The position for update has been forgotten because of the following GET. 
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Example 9: Keyed-Direct Update 


PUT 


In this example, GET and PUT macros are used to retrieve and update records. 
The MODCB macro is used to modify record length (RECLEN) in the request 
parameter list when an update causes the record length to change. The 
maximum record length is 120 bytes. The search argument is a full key (5 bytes), 


compared equal. 


INPUT ACB 


UPDTE RPL 


MACRF=(KEY,DIR, 
- OUT) 


UPDTE indicates the record 
may be stored back 
(or deleted). 


ACB=INPUT, 


KEYLEN=5 


Process input and get search argument into KEYAREA; proceed 
to retrieve a record. 


LOOP GET 
LTR 
BNZ 


SHOWCB 


LTR 
BNZ 


Update the record. 


length? 
BE 
L 


MODCB 


LTR 
BNZ 
PUT 
LTR 
BNZ 


STORE 


RPL=UPDTE 
15,15 

ERROR 
RPL=UPDTE, 
AREA=RLNGTH, 
FIELDS=RECLEN, 
LENGTH=4 
15,15 


CHECKO 


Display the length of the 
record. 


Does the update change the record's 


STORE No; length not changed. 

5, length Yes; load new length into 
register 5. 

RPL=UPDTE , Modify length indication 

RECLEN=(5 ) in the request parameter 
list. 

15,15 

CHECKO 

RPL=UPDTE 

15,15 

ERROR 

LOOP 
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PUT 


ERROR 

CHECKO... 

IN DS CL120 
KEYAREA DS CLS 
RLNGTH ODS F 


Request was not accepted, or 
failed. 


Display or modification 
failed. 


Work area for retrieving, 
updating, and storing a 
record. 


Search argument for 
retrieving a record. 


Area for displaying the 
length of a retrieved record. 


You cannot update records in the I/O buffer. A direct GET for update positions 
VSAM at the record retrieved, in anticipation of storing back (or deleting) the 
record. This positioning also allows you to switch to sequential access to retrieve 
the next record. When PUT is issued after a DIRUPD GET request, PUT 


causcs VSAM to release exclusive control. 


You do not have to store back a record that you retrieve for update, but, if you 
do not store it back before another retrieval, the current updates are lost. 
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Example 10: Addressed-Sequential Update 


PUT 


In this example, GET and PUT macros are uscd to retrieve and update records in 
an entry-sequenced data set. The records are variable in length, a maximum of 
200 bytes. The lengths of the records are not changed by update (the length of a 
record can never be changed by addressed access). . 


ENTRY 
ADRUPD 


ACB 
RPL 


GET 
LTR 
BNZ 
SHOWCB 


LOOP 


LTR 
BNZ 
PUT 
LTR 
BNZ 
ERROR... 


CHECKO ... 


WORK 
RLNGTH 


MACRF=(ADR, SEQ, OUT) 


ACB=ENTRY, UPDTE indicates update (or 
AREA=WORK, deletion). 
AREALEN=200, 
OPTCD=(ADR, SEQ, 
SYN, UPD, MVE) 
RPL=ADRUPD 
15,15 
ERROR 
RPL=ADRUPD, Find out how long the record 
AREA=RECLEN, is. 
FIELDS=RECLEN, 
LENGTH=4 
15,15 
CHECKO 
RPL=ADRUPD 
13,15 
ERROR 
LOOP 
Request was not accepted, or 
failed. 
Display failed. 
CL200 Record-processing work area. 
F Display area for length of 


records. 


If you have inactive records in your entry-sequenced data sect, you may reuse the 
space they occupy by retrieving the records for update and restoring a new record 


in their place. 


With a key-sequenced data sct, it is not possible to change the Iength of records 
by addressed update because the index is not used and VSAM could not split a 
control interval if required because of changing record length. 


Addressed-direct update varies from sequential update in the specification of an 
RBA for a search argument. 
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Example 11: Marking Records Inactive 


In this example, GET and PUT macros are used to retrieve a record from an 
entry-sequenced data set and to mark it as inactive. (The record is marked as 
inactive by putting a hexadecimal ‘FF’ in the first byte of a record.) The inactive 
record will not be sequentially retrieved except for update. 


ENTRYSEQ ACB 
LIST RPL 
LOOP GET 
LTR 
BNZ 


MACRF=(ADR, DIR, 
OUT) 


ACB=ENTRYSEQ, 
AREA=RECORD, 
AREALEN=100, 
OPTCD=(ADR, DIR, 
SYN,UPD,MVE), 
ARG=RBAAREA 


UPD indicates update; 
storing the record back 
marked inactive... 


RPL=LIST 
15,15 
ERROR 


Decide whether you still want the data in the record. 


BE 


MVI 


PUT 


LTR 


BNZ 


ERROR 


RECORD DS 


RBAAREA DS 


LOOP Yes; retrieve the next 


record. 


RECORD, X'FF’ No; flag the record 


inactive. 

RPL=LIST Storing the record with 
an inactive indicator is 
equivalent to deletion 
for an entry-sequenced 
data set. 

15,15 

ERROR 

LOOP 
Request was not accepted, 
or failed. 

CL100 Work area for marking 
records. 

F Search argument for 


retrieving the record. 


Records of an entry-sequenced data sct can’t be deleted. If a record loses its 
usefulness for your application, your program can mark it inactive by placing a 
unique flag in some conventional part of the record so that when your programs 
retrieve the record thereafter they can recognize and bypass it. You can use the 
space occupied by an inactive record by retrieving it for update and storing a new 


record in its place. 
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PUTIX Macro (Store an Index Record) 


The format of the PUTIX macro is: 


Jlabe} PUTIX | RPL= address 


where: | 


label 
is 1 to 8 characters that provide a symbolic address for the PUTIX macro. 


RPL = address 
specifics the address of the request parameter list that defines this PUTIX 
request. You may specify the address in register notation (using a register 
from | through 12, enclosed in parentheses) or specify it with an expression 
that gencrates a valid relocatable A-type address constant. 


The following RPL parameters and subparameters are required for PUTIX: 
OPTCD = (CNV 

DIR 

UPD 

MVE) 

OPTCD= LOC 1s not allowed. 


AREALEN 
must be at least index control interval size. 


The contents of a control interval must previously have been retrieved for update 
by way of GETIX. 


To process the index of a key-sequenced data set with GETIX, you must open 
the cluster with: 


ACB MACRF=(CNV,...) 
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RPL Macro (Generate a Request Parameter List at Assembly Time) 


The format of the RPL macro is: 


[ACB = address} 

{,AM = VSAM] 

[,AREA = address] 

|, AREALEN = number| 

[,ARG = address} 

[,.ECB = address} 

[| ,.KEYLEN = number] 

|, MSGAREA = address] 

|, MSGLEN = number| 

|, NXTRPL = address] 

[,.OPTCD = ({ADR|CNV|KEY] 
[, DIR|SEQ|SKP] 
| ARDILRD| 
[.FWD|BWD] 
| ASY|SYN] 
|. NSP|NUP|UPD| 
|, KEQIKGE| 
| EKS|GEN| 
J NWAITX|WAITX] 
[,LLOC|MVED] 

J, RECLEN = numbert 
[, FRANSID = number] 





Values for RPL macro parameters can be specified as absolute numeric 
expressions, character strings, codes, and expressions that gencrate valid 
relocatable A-type address constants. 


label 
is 1 to 8 characters that provide a symbolic address for the request 
parameter list that is generated. You can use it in the request macros to 
give the address of the list. You can use it in the NXTRPL parameter of 
the RPL macro, when you are chaining request parameter lists, to indicate 
the next list. 


ACB = address 
specifies the address of the access method control block that identifies the 
data sect to which access will be requested. If you uscd the ACB macro to 
generate the control block, you may specify the label of that macro for the 
address. If the ACB parameter is not coded, you must specify the address 
before issuing the request. 


AM = VSAM 
specifics that the access method using the control block is VSAM. 


AREA = address 
specifies the address of a work area to and from which VSAM moves a data 
record if you request it to do so (with the RPL parameter 
OPTCD= MVE). If your request is to process records in the I/O buffer 
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(OPTCD=LOC), VSAM puts into this work area the address of a data 
record within the I/O buffer. 


AREALEN = number 
specifies the length, in bytes, of the work area whose address is specified by 
the AREA parameter. Its minimum for OPTCD= MVE is the size of a 
data record (of the largest data record, for a data set with records of variable 
length). For OPTCD= LOC, the area should be 4 bytes to contain the 
address of a data record within the I/O buffer. 


ARG = address 
specifies the address of a field that contains the search argument for direct 
retrieval, skip-sequential retrieval, and positioning. For a relative record 
data set, the ARG ficld must be 4 bytes long. For direct or skip-sequcential 
processing, this field contains your scarch argument, a relative record 
number. For sequential processing (OPTCD=(KEY,SEQ)), the 4 bytes 
are required for VSAM to return the feedback RRN. For keyed access 
(OPTCD= KEY), the search argument is a full or generic key or relative 
record numbcr; for addressed access (OP TCD= ADR), it is an RBA. If 
you specify a generic key (OPTCD = GEN), you must also specify in the 
KEYLEN parameter how many of the bytes of the full kcy you are using 
for the generic key. ARG 1s also used with WRTBIFR and MRKBER. Its 
usage with these macros is described in “Sharing Resources” in VSAM 
Administration Guide. 


ECB = address 

specifies the address of an event control block (ECB) that you may supply. 

VSAM indicates in the ECB whether a request is complete or not (using 
standard completion codes, which are described in Data Areas). You can 

use the ECB to determine that an asynchronous request is complete before 

issuing a CHECK macro. (If you issue a CHECK before a request is 

complete, you give up control and must wait for completion.) ‘The ECB 

parameter is always optional. 


KEYLEN = number 
specifies the length, in bytes, of the generic key (OP TCD = GEN) you are 
using for a search argument (given in the field addressed by the ARG 
parameter). This parameter is specified as a number from | through 255; it 
is required when the search argument is a generic key. For full-key 
searches, VSAM knows the key length, which is taken from the catalog 
definition of the data sct when you open the data sct. 


MSGAREA = address 
specifies the address of an area that you may, optionally, supply for VSAM 
to send you a message in case of a physical error. The format of a physical 
error message is given in “Reason Code (Physical Errors)” on page 26. 


MSGLEN = number 
specifies the size, in bytes, of the message area indicated in the MSGAREA 
parameter. If MSGAREA is specified, MSGLEN is required. The 
minimum size of a message is 128 bytes; if you provide less than 128 bytes, 
no message is returned to your program. 
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NXTRPL = address 


specifies the address of the next request parameter list in a chain. Urnit this 
parameter from the macro that generates the last list in the chain. When 
you issue a request that is defined by a chain of request parameter lists, 
indicate in the request macro the address of the first parameter list in the 
chain. 


OPTCD = ((ADRICNV|KEY] 


[, DIR|SEQISKP| 

| ARD|LRD] 

LEWD|BWD] 

LASYISYNJ 

|, NSP|NUP|UPD] 

| KEQIKGE] 

LFKS|GEN] 

[ NWAITX|WAITX] 

[,LOC|MVE)) 

specifies the subparamcters that govern the request defined by the request 
parameter list. Each group of subparameters has a default; subparamcters 
are shown in Figure 13 with defaults underlined. Only one subparameter 
from each group can be specified. Some requests do not require an 
subparameter from all of the groups to be specificd. The groups that aren't 
required arc ignored; thus, you can use the same request parameter list for a 
combination of requests (GET, PUT, POINT, for example) without 
zcroing out the inapplicable subparameters cach time you go from one 
request to another. 


Option Meaning 


ADR 


CNV 


KEY 


DIR 


SE 


SKP 


Addressed access to a key-scquenced or an entry-sequenced 
data sct: RBAs are used as scarch arguments and sequential 
access is done by entry sequence. 


Control interval access (this type of access is described in 
VSAM Administration Guide). 


Keyed access to a key-sequenced or relative record data set: 
keys or relative record numbers are used as search arguments 
and sequential access is done by key or relative record number 
sequence. 


Direct access to a key-sequenced, entry-sequenced, or relative 
record data set. 


Sequential access to a key-sequenced, entry-sequenced, or 
relative record data set. 


Skip sequential access to a key-sequenccd or a relative record 
data set: used with keyed access only. 


Figure 13 (Part 1 of 3). OPTCD Options 
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Option 
ARD 


LRD 


FWD 
BWD 


ASY 


SYN 


NSP 


NUP 


. UPD 


KEQ 


RPL 


Meaning 


User’s argument determines the record to be located, retrieved, 
or stored. 


Last record in the data set is to be located (POINT) or 
retrieved (GET direct); requires OPTCD= BWD. 


Processing to proceed in a forward direction. 


Processing to proceed in a backward direction; for keyed 
(KEY) or addressed (ADR) sequential (SEQ) or direct (DIR) 
requests; valid for POINT, GET, PUT, and ERASE 
operations; establish positioning by a POINT with 
OPTCD=BWD or by a GET dircct with 
OPTCD=(NSP,BWD). When OPTCD= BWD is specificd, 
subparameters KGE and GEN are ignored; subparameters 
KEQ and FKS are assumed. 


Asynchronous access; VSAM returns to the processing 
program aftcr scheduling a request so the program can do other 
processing while the request is being carried out. 


Synchronous access; VSAM returns to the processing program 
after completing a request. 


With OPTCD= DIR only, VSAM is to remember its position 
(for subsequent sequential access); that is, the position is not to 
be forgotten unless an ENDREQ macro 3s issued. 


A data record that is being retneved will not be updated or 
deleted; a record that is being stored is a new record; VSAM 
doesn’t remember its position for direct requests into a work 
arca. 


A data record that is being retrieved may be updated or deleted; 
a record that is being stored or delcted was previously retneved 
with C2TCD= UPD; VSAM remembcrs its position for 
sequential and direct GET requests. When PUT is issued after 
a DIRUPD GET request, PUT causes VSAM to release 
exclusive control. 


For GET with OPTCD=(KEY,DIR) or (KEY,SKP) and for 
POINT with OPTCD= KEY, the key (full or generic) that you 
provide for a search argument must cqual the kcy or relative 
record number of a record. For a rclative record data set, KEQ 
is assumed except for POINT. 


Figure 13 (Part 2 of 3). OPTCD Options 
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Option 
KGE 


FKS 
GEN 


NWAITX 


WAITX 


LOC 


MVE 


Meaning 


For the same cases as KEQ, if the key (full or generic) that you 
provide for a search argument doesn’t equal that of a record, 
the request applies to the record that has-the next higher key. 
For a relative record data set and POINT, KGE positions to 
the specified relative record number whether the slot is empty 
or not. If the relative record number is greater than the highest 
existing record, EOD is returned. A subsequent PUT will 
insert the record at this position. 


A full key is provided as a search argument. 


A generic key is provided as a search argument; give the length 
in the KEYLEN parameter. 


Never take the user’s UPAD exit. 


If OPTCD=SYN and the ACB’s MACRF = LSR GSR and 
UPAD exit routing is specified, VSAM takes the UPAD exit at 
points when VSAM would normally issue a WAIT. 


Kor retrieval, VSAM leaves the data record in the I/O buffer 
for processing; not valid for PUT or ERASE; valid for GET 
with OPTCD= UPD. However, to update the record, you 
must build a new version of the record in a work area and 
modify the request parameter list OPTCD from LOC to MVE 
before issuing a PUT. For keyed-sequential retricval, 
modifying key fields in the I/O buffer may cause incorrect 
results for subsequent GET requests until the I/O record is 
reread. 


For retrieval, VSAM moves the data record to a work arca for 
processing, and for storage, VSAM moves it from the work 
area to the I/O buffer. 


Figure 13 (Part 3 of 3). OPTCD Options 


RECLEN = number 
specifies the length, in bytes, of a data record being stored. This parameter 
is required for a PUT request. 


For GET requests, VSAM puts the length of the record retrieved in this 
ficld in the request parameter list. It will be there if you update and store 
the record. 


TRANSID = number 
specifics a number that relates modified buffers in a buffer pool. Used in 
shared resource applications and described in the chapter “Sharing 
Resources” in VSAM Administration Guide. 
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Example: RPL Macro 


RPL 


In this example, an RPL macro 1s used to generate a request parameter list 
named PARMLIST. 


ACCESS ACB MACRF=(SKP,OUT), 
DDNAME=PAYROLL 


PARMLIST RPL ACB=ACCESS, 
AM=VSAM, 
AREA=WORK, 
AREALEN=125, 
ARG=SEARCH, 
MSGAREA=MESSAGE, 
MSGLEN=128, 
OPTCD=(SKP, UPD) Most OPTCD defaults are 


appropriate to assumptions. 
WORK DS CL125 


SEARCH DS CL8 
MESSAGE DS CL128 


The ACB macro named ACCESS, spccifics skip-scqucntial retrieval for update. 
Further details may be provided on a DD statement named PAYROLL. 


The RPL macro’s parameters are: 


@¢ ACB associates the request parameter list with the access mcthod control 
block generated by ACCESS. 


e AREA and AREALEN spccify a work area, WORK, that is 125 bytcs long. 


6 ARG specifics that the search argument is defined at SEARCH. Whe scarch 
argument 1s 8 bytcs long. 


e MSGAREFA and MSGLEN spccify a message area, MESSAGE, that is 128 
bytes long. The message area is provided for physical error messages. 


© OPTCD specifics skip-sequential processing and specifies that a retrieved 
record may be updated or deleted. 


Because KEYLEN 1s not coded, a full-key search is assumed. 
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SCHBFR Macro (Search Buffer) 


The format of the SCHBFR macro is: 


SCHBFR | [BFRNO = number] 
IRPL = address 
BFRNO = number 
specifies the number of the buffer VSAM is to search first. The buffers 
preceding it in the buffer pool are not searched. The default 1s 1; that is, 
the first buffer is searched first. (If the number is coded in register notation, 
all registers except 1 and 13 may be used.) 


RPL = address 


specifies the address of the request parameter list that defines the SCLIBFR 
request. These RPL parameters have meaning for SCHIBFR: 


ACB = address 
AREA = address 
If a buffer is found, the area whose address is specified will contain its 
address (OPTCD= LOC) or a copy of its contents (OPTCD = MVE). 
AREALEN = number 
At least 4 with OPTCD= LOC; at least control interval size with 
OPTCD= MVE. 
ARG = address 
ARG gives the address of an 8-byte field that contains the beginning 


and ending control interval RBAs of the range to be searched on. 


ECB = address 

OPTCD= ASSIA OEE 

TRANSID = number 

All other RPL parameters are ignored. RPLs are assumed not to be 


chained. Control interval access is assumed. 


If the ACB to which the RPL is related has MACRF=GSR, the program 
that issues SCHIBFR must be in supervisor state with protection key 0 to 7. 
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SHOWCB—ACB 


SHOWCB Macro (Display Fields of an Access Method Control Block) 


The format of the SHOWCB macro used to display ficlds in an access method 
control block is: 


[label SHOWCB | ACB= address 

AREA = address 

j§LENGTH = number 

| OBJECT = DATA|INDEX] 

FIELDS = ((ACBLEN] |, AVSPAC] 
[,BFRFND][,BSTRNO] 
|,BUFNO] [,BUFRDS] 
],BUFSP] 
[|,CINV] |, DDNAME]LENDRBA] 
|,ERROR] [,EXLST]],FS] 
|,HALCRBA] [,KEYLEN]|,LRECL] 
|,MAREA] [,MLEN][,NCIS] 
[ NDELR] [,NEXCP]],NEXT] 
[.NIXL] |. NLOGR]L,NRETR] 
[,NUIW] | ,NUPDR]],PASSWD] 
LSHRPOOL] [, STMST],STRMAX] 
[,STRNO] [,UIW) 





The parameters of the SHOWCB macro can be expressed as absolute numeric 
expressions, as character strings, as codes, as expressions that gencrate valid 
relocatable A-type address constants, in register notation, as S-type address 
constants, and as indirect S-type address constants. Appendix C, “Opcerand 
Notation” on page 181, further dcfines these operand expressions. 


label 


is | to 8 characters that provide a symbolic address for the SIIOWCB 
macro. 


ACB = address 
specifies the address of the access method control block whose ficlds are to 
be displayed. If you used the ACB macro with a label, you can specify the 
label here. The ACB parameter is optional when you wish to display the 
length of an access method control block (FIEILDS = ACBLEN). (All 
access method control blocks have the same Icngth, so you need not specify 
the address of a particular onc.) 


AREA = address 
specifics the address of a work arca that you are supplying for VSAM to 
display the contents of the ficlds you specify in the FIELDS parameter. 
The contents of the fields are displayed in the order in which you specify 
them. The area must begin on a fullword boundary. 


LENGTH = number 
specifies the length, in bytes, of the work area that you are providing for 
VSAM to display the indicated fields in. (See the FIELDS parameter for 
the fields that can be displayed and for the length of each field.) If the area 
is not large enough for all the fields, VSAM doesn’t display any of their 
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contents and returns a reason code (see “Control Block Manipulation 
Macro Return Codes and Reason Codes” on page 10). 


OBJECT = DATA|INDEX 
specifies whether fields are to be displayed for the data or for the index. 


FIELDS = [ACBLEN]],AVSPAC] 
|, BEREND][,BSTRNO} 
|, BUFND][, BUFNI} 
|, BUFNO][,BUFRDS} 
[ BUFSP][,CINV] 
| DDNAME],.ENDRBA] 
| ,.ERROR],EXLST] 
L,.FS]],HALCRBA] 
[| KEYLEN|,LRECL] 
|, MAREA][, MLEN] 
[,NCIS|LNDELR] 
[LNEXCPH,NEXT] 
[.NINSRILNIXL] 
| NLOGR]],NRETR] 
LNSSS],NUIW] 
[,NUPDR]],PASSWD] 
[ RKP], SHRPOOL] 
[ STMST]L.STRMAX] 
|, STRNO],CIW)) 
specifies the fields whose contents are to be displayed. Same of the fields 
can be displayed at any time; others only after a data set is opened. The 
ones that can be displayed only after_a data set is ope in the case of 
a key-sequenced data set that has been opened for keyed access pertain 
“SIRE? To The taerorto The HUG Sco the OBJECT parameter. Figure 14 
‘explains the Keywords you can code in the FIELDS parameter for an access 


method control block. 





Keyword Fullwords —_— Description of the Field 


Note: The following fields can be displayed at any 
time. 


ACBLEN I Length of an access method control block 
(displaying the length of an access method control 
block gives your program independence from 
changes in the Iength that may occur from relcase 
to release of VSAM) 


BSTRNO 1 Number of strings initially allocated for access to 
the base cluster by a path 


BUFND 1 Number of I/O buffers to be used for data, as 
specified in the ACB (or GENCB) 


Figure 14 (Part 1 of 4). FIELDS Operand Keywords for an Access Method Control 
Block 
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Keyword Fullwords _—_ Description of the Ficld 


BUFNI 1 Number of I/O buffers to be used for index entrics, 
as specified in the ACB (or GENCB) 

BUFSP 1 Amount of space specified in the ACB (or 
GENCB) for I/O buffers 

DDNAME 2 Name of the DD statement that identifies the data 
sct 

ERROR 1 The code returned by VSAM after the opening or 


closing of the data set (sec “OPEN Macro (Connect 
Program and Data)” on page 107 and “CLOSE 
Macro (Disconnect Program and Data)” on 


page 55). 
EXLST 1 Address of-the exit list, if any; 0 if none 
MAREA | Address of the message arca, if any; 0 if nonc 
MLEN l Length of the message arca, if any; 0 if none 
PASSWD |! Address of the ficld containing the password; the 


first byte of the ficld contains the Iength of the 
password (in binary) 


SHRPOOL 1 Identification number of resource pool to be used 
for LSR processing 

STRMAX 1 Maximum number of strings concurrently active 

STRNO 1 ‘Number of requests for which VSAM is prepared 
to remembcr its position in the data sct 
Note: The following ficlds can be displayed only 
after the data sct is opencd. 

AVSPAC 1 Amount of available space in the data component 
or index componcnt, in bytes 

BFRFND 1 Number of successful look-asides 

BUFNO l Number of I/O buffers actually in use for the data 
component or index component 

BUFRDS 1 Number of buffer reads 

CINV 1] Control interval size for the data component or 


index componcnt 





Figure 14 (Part 2 of 4). FIELDS Operand Keywords for an Access Method Control 
Block 


ss e, 
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Keyword 
ENDRBA | 


FS 


HALCRBA 


KEYLEN 


LRECL 


NCIS 


NDELR 


NEXCP 


NEXT 


NINSR 


NIXL 


NLOGR 


NRETR 


NSSS 


Fullwords 
| 


1 


Description of the Field 


Ending RBA of the space used by the data 


component or index component; not the RBA of 
any record in the data set, but of the last used byte 
in the data set 


Number of free control intervals per control area in 
the data componcnt (0 for OBJECT = INDEX) 


High-allocated RBA; the relative byte address of the 
end of the data component (OBJECT = DATA) or 
the index component (OBJECT = INDEX) 


Length of the key of reference of the key ficld of 
data records in the data component (whcther 
OBJECT = DATA or INDEX) 


Length of data records in the data component 
(maximum Iength for variable-length data records) 
or of index records in the index component (control 
interval length minus 7) 


Number of control intervals that have been split in 
the data component (0 for OBJECT = INDEX) 


Number of records that have been deleted from the 
data. component (0 for OBJECT = INDEX) 


Number of EXCP macros that VSAM has issued 
for access to the data component or index 
component. 


Number of extents now allocated to the data 
component or index componcnt (the maximum 
that can be allocated in 123) 


Number of records that have been inserted into (or 
added to) the data component (0 for 
OBJECT = INDEX) 


Number of levels in the index component (0 for 
OBJECT = DATA) 


Number of records in the data component or index 
component 


Number of records that have ever been retrieved 
from the data component (0 for 
OBJECT = INDEX) 


Number of control areas that have been split in the 
data componcnt (0 for OBJECT = INDEX) 


Figure 14 (Part 3 of 4). FIELDS Operand Keywords for an Access Method Control 
Block 
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Keyword Fullwords Description of the Ficld 

NUIW 1 Number of writes not initiated by the user - 

NUPDR 1 Number of records in the data component or index 
component that have ever becn updated 

RKP l Displacement of the key of reference of the key field 
from the beginning of a data record (whether 
OBJECT = DATA or INDEX) 

STMST 2 System time stamp, which gives the time and day of 
the last time the data component or index 
component was closed, with bit 51 (counting from 
0 at the Icft) equivalent to one microsecond and bits 
52 through 63 unuscd 

UIW ] Number of user-initiated writes 


Figure 14 (Part 4 of 4). FIELDS Operand Keywords for an Access Method Control 
Block 


Example 1: SHOWCB Macro (Display an Access Mcthod Control Block) 


In this example, a SHIOWCB macro is uscd to display fields in an access method 
control block. The fields displayed (KEYLEN, LRECL, and RKP) permit the 
program to modify variables to process any one of a number of data scts that 
have different sized key ficlds and records and different placements of key ficld in 


a record. 
SHOWCB ACB=CONTROL, 

AREA=DISPLAY, 

FIELDS=(KEYLEN, 

LRECL, RKP), 

LENGTH=12 
DISPLAY DS OF Align on fullword boundary. 
KEYLEN DS 
LRECL ODS 
RKP DS 


The SHIOWCB macro’s parameters are: 


e ACB specifics the address of the access method control block to be displayed. 


e AREA specifics that the area to be used to display access mcthod control 
block fields is to begin on a fullword boundary. 


e FIELDS specifies that the KEYLEN, LRECL, and RKP fields are to be 


displayed. 


e LENGTH specifies that the length of the area to be used for the display is 12 
bytes, enough to accommodate the specified fields. 
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This display enables the program to set up its variables for the particular data set 
it has opened. 


Example 2; SHOWCB Macro (Display an Exit List Address) 


In this example, a SHIOWCB macro is used to get the address of an exit list by 
displaying the address in an access method control block that uses the exit list. 
SHOWCB ACB=address, 
AREA=address, 


FIELDS=EXLST, 
LENGTH=4 


The SHOWCB macro’s parameters are: 


e ACB specifies the address of an access method control block from which the 
address of an exit list is to be displayed. 


e AREA and LENGTH specify an area and Iength, 4 bytes, to be uscd to 
display the address of the exit list. 


e =6FIELDS specifies that the EXLST field in an access method control block is 
to be displayed. 
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SHOWCEB Macro (Display Fields of an Exit List) 
The format of the SHOWCB macro used to display ficlds in an exit list is: 


[label SHOWCB | EXLST = address 
AREA = address 


,LENGTH = number — 
FIELDS = ((EODAD] [,EXLLEN] [, JRNAD] 
| LERAD],SYNAD)) 





The subparamcters of the SHIOWCB macro can be expressed as absolute numeric 
expressions, as character strings, as codes, as expressions that gencrate valid 
relocatable A-type address constants, in registcr notation, as S-type address 
constants, and as indirect S-type address constants. Appendix C, “Operand 
Notation” on page 181, further defines these operand expressions. 


label 
is | to 8 characters that provide a symbolic address for the SUIOWCB 
macro. 


EXLST = address 
specifies the address of the exit list whose fields are to be displayed. If you 
used the EXLST macro with a label, you can specify the label here. The 
EXLST parameter is optional only when you want to display the length 
that an exit list can have (sce FIELDS = EXLLEN below). The SHOWCB 
macro does not support the UPAD user exit. 


AREA = address 
specifics the address of a work arca that you are supplying for VSAM to 
display the contents of the fields you specify in the FIELDS parameter. 
The contents of the fields are displayed in the order you specify them. The 
arca must begin on a fullword boundary. 


LENGTH = number 
specifies the length, in bytes, of the work area that you are providing for 
VSAM to display the indicated fields in. Each exit-list field requires a 
fullword. If the arca is not large enough for all the ficlds, VSAM doesn’t 
display any of their contents and returns an error code (sce “Control Block 
Manipulation Macro Return Codes and Reason Codecs” on page 10). 


FIELDS = (EODAD]],EXLLEN][,JRNAD] 
[,LERAD],SYNAD) 
specifics the valucs to be displayed, as follows: 


EODAD 
specifies that the address of the end-of-data-set routine is to be 
displayed. 


EXLLEN 
specifies that the length of the exit list indicated in the EXLST 
parameter or if EXLST is omitted, the maximum length an exit 
length can have, is to be displayed. 
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JRNAD 
specifies that the address of the journalizing routine is to be displayed. 


LERAD 
specifies that the address of the logical error analysis routine is to be 
displayed. 


SYNAD 
specifies that the address of the physical error analysis routine is to be 
displaycd. 


You can use SIIOWCB to display the address of an exit routine only if the exit 
routine is indicated in the exit list. If it isn’t, the SHOWCB request will fail. Use 
TESTCB to test whether an entry for a given exit type is present in the exit list 
and to find out whether the exit is active and whether the routine is to be loaded. 


Example: SHOWCB Macro (Display the Length of an Exit List) 


In this example, a SHWOQWCB macro is used to display the maximum Iength of an 
exit list. The maximum length of an exit list is subsequently used in a GENCB 
macro to get virtual storage for an exit list. 


SHOWCB AREA=LENGTH, 
FIELDS=EXLLEN, 


LENGTH=4 
L O, LENGTH | Amount of storage for 
GETMAIN. 
GETMAIN R, LV=(0) 
LR 2,1 Address of storage for 
GENCB. 

GENCB BLK=EXLST, Indirect notation for 
LENGTH=(*, length of work area. 
LENGTH) , 

WAREA=( 2) 
LENGTH DS F Contains the length of 


GENCB's work area. 
The SHOWCB macro’s parameters are: 


® AREA and LENGTH specify the area, which begins on a fullword 
boundary, and its length, four bytes, that is to be uscd for the display. 


e FIELDS specifies that the maximum length of an exit list is to be displayed. 
Because only EXLLEN is specified, the EXLST parameter is omitted. 


The GENCB macro specifies a work area in which an exit list is to be generated. 


The length of the work arca is located at LENGTH, where the maximum length 
of an exit list was put as a result of the SHOWCB macro. 
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SHOWCB Macro (Display Fields of a Request Parameter List) 


_ The format of the SHOWCB macro uscd to display fields in a request parameter 
list 1s: 


SHOWCB | RPL= address . 
AREA = address 
»§LENGTH = number . 
FIELDS = ({ACB][,AIXPC][,AREA]],AREALEN] 
|, ARG],ECB]L,FDBK]],FINCD] 


|. KEYLEN]], MSGAREA] 
|. MSGLEN] 
{.NXTRPLILRBA| 
,RECLEN] 

L.RPLLEN] 

|, TRANSID)) 





The parameters of the SIIOWCB macro can be expressed as absolute numeric 
expressions, as character strings, as codes, as expressions that gencrate valid 
relocatable A-type address constants, in register notation, as S-type address 
constants, and as indirect S-type address constants. Appendix C, “Opcrand 
Notation” on page 181, further defines these operand expressions. 


label 
is 1 to 8 characters that provide a symbolic address for the SYOWCB 
macro. 


RPL = address 
specifics the address of the request parameter list whose ficlds are to be 
displayed. If you used the RPL macro with a label, you can specify the 
label here. The RPL paramcter is optional when you want to display the 
Iength of a request paramcter list (FIELDS =RPLLEN). (All VSAM 
request parameter lists have the same Iength, so you need not specify the 
address of a particular one.) 


AREA =.address 
specifics the address of a work area that you are supplying for VSAM to 
display the contents of the fields you specify in the FIELDS parameter. 
The contents of the ficlds are displayed in the order you specify them. The 
arca must beyin on a fullword boundary. 


LENGTH = number 
specifics the length, in bytes, of the work arca that you arc providing for 
VSAM to display the indicated ficlds in. Each request parameter list field 
requires a fullword. If the arca is not large enough for all the fields, VSAM 
doesn’t display any of their contents and returns an error code (see 
“Control Block Manipulation Macro Return Codes and Reason Codes” on 


page 10). 
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FIELDS = ({ACB][,AIXPC]], AREA]],AREALEN]],ARG] 
|, ECBI,.FDBK]{,FTNCD][,KEYLEN] 
[, MSGAREA]], MSGLEN] 
|, NXTRPL]],RBA]|,RECLEN] 
[,.RPLLEN|[,TRANSID)) ; 
specifies the fields whose contents are to be displayed. Figure 15 on 
page 142 explains the keywords you can code in the FIELDS parameter for 
a request parameter list. Some fields (each indicated by an asterisk (*) in 
Figure 15) are meaningful only if the requests have been completed; 
therefore, you must wait until the requcst has completed (for example, by 
issuing a CHECK if the request is asynchronous) before issuing SIIOWCB. 


Keyword Fullwords Description of the Ficld 


ACB l Address of the access method control block that 
relates the request parameter list to the data 

AIXPC* I ‘Number of alternate index pointers 

AREA 1 Address of the work area that the program uses to 


proccss a data record for the access as defined by 
the request parameter list 


AREALEN 1 Length of the work area whose address is given in 
AREA 

ARG l Address of the field containing a scarch argument, 
if search arguments are being used 

ECB* 1 Address of an event control block, if any, in which 


VSAM indicates the completion of requests 
defined by the request parameter list 


FDBK* | Reason code that VSAM puts into the fecdback 
ficld to describe the error detected for the 
preccding requcst. (The meaning of this code 
depends on the contents of register 15, which 
indicates whether the request was successful or 
failed because of a logical or physical error. See 
“Record Management Return Codes and Reason 
Codes” on page 13) 


FINCD* l Code that describes the function in which a logical - 
or physical crror occurred; indicates whether the 
upgrade sct may have been modified incorrectly by 
the preceding request (‘The meaning of this code 
depends on the contents of register 15, which 
indicates whether the requcst was successful or 
failed because of a logical or physical crror. See 
“Record Management Return Codes and Reason 
Codecs” on page 13) 





Figure 1S (Part 1 of 2). FIELDS Operand Keywords for a Display Request Parameter 
List 
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Keyword Fullwords 
KEYLEN ] 


NISGAREA* 1 


MSGLEN ] 
NATRPL l 


RBA* 1 
RECLEN* 1 
RPLLEN ] 


TRANSID 1 


SHOWCB—RPL 


Description of the Ficld 


Length of the scarch argument, if a generic key is 
used for a search argument 


Address of the area, if any, into which VSAM puts 
physical error messages © 


Length of the message area, if any | 


Address of the next request parameter list, if 
another onc is chaincd to this one 


Relative byte address of the most recently 
processed record; you could use it to record the 
RBAs of records that you are retricving or storing 
sequentially or by key 


Length of the data record, access to which is 
defined by the request parameter list 


Length of a request paramcter list 


Number that relates modificd buffers in a buffer 
pool; described in VSAM Administration Guide 


Figure 15 (Part 2 of 2). FIELDS Operand Keywords for a Display Request Parameter 


List 
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Example: SHOWCB Macro (Display a Physical Error Message) 


In this example, a SHOWCB macro is used to display a physical error message. 
This example assumes that there is no SYNAD routine (or the SYNAD exit 1s 
inactive), in which case, VSAM retums control to your program following the 
last executable instruction if a physical crror occurs. Register 15 indicates a 
physical error (12), and the feedback field in the request parameter list contains a 
code identifying the crror; the message arca contains more details about the error. 
Register | points to the request parameter list. 


REQUEST RPL MSGAREA= 
MESSAGES, 
MSGLEN=128 


SHOWCB AREA=MSGADDR, 
FIELDS=MSGAREA, 
LENGTH=6, 
RPL=REQUEST 

LTR 15,15 


BNZ CHECKO 


CHECKO ... Display failed. 


MESSAGES DS CL128 For VSAM to give you a 
detailed message about 
a physical error. 


MSGADDR DS F For displaying the 
address of the message 
area with SHOWCB. 


The RPL macro in this example provides for a message area, MESSAGES, of 
128 bytes to be used for any physical error message. 


The SHOWCB macro’s parameters are: 

e AREA and LENGTII specify a 4-byte area, MSGADDR, to be used for 
displaying the address of the message arca for the associated request 
paramcter list. 


e FIELDS specifies that the address of the message area is to be displayed. 


e RPL specifies the name, REQUEST, of the request parameter list for which 
the message arca address is to be displayed. 
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| TESTCB Macro (Test Fields of an Access Method Control Block) 


Only one kcyword can be specified each time you issue TESTCB. The format of 
the TESTCB macro used to test a field in an access method control block 1s: 


TESTCB)} ACB= address 
[ ,EREF = address} 
_ | LOBJECT = DATAIINDEX] 
| {ATRB = (IESDS]],KSDS]], LDS]], REPL] 

| RRDS]],SPAN|],SSWD]|,WwCK]| 

ATRB= UNQ| 

CATALOG = YES|NO| 

CRA = SCRA|UCRA| 

MACRF = ((ADRJ,AIX][,CFX]],CNV|IL,DDN] 
[,DFR][,DIR][,DSN][,GSR]f,1CHL EN] 
LL KEY]. LSR]],NCI,NFDILL.NEX],NIS] 
LNRMINRSILNSRUL,NUB]L,OUTILRST 
[ SEQ]LSIS]],SKPI],UBF))| 

OFLAGS = OPEN | 

OPENOBJ = PATH|BASE|AIX| 

ACBLEN = number| 

AVSPAC = number| 

BSTRNO = number| 

BUFND = number| 

BUFNI = number| 

BUFNO = number| 

BUFSP = number| 

CINV = number| 

DPDNAME= ddnamie] 

ENDRBA = number| 

ERROR = number| 

EXLST = address| 

FS = number| 

KEYLEN = number| 

LRECL = number| 

MAREA = address| 

MLEN = number| 

NCIS = number| 

NDELR = number| 

NEXCP = number| 

NEXT = number| 

NINSR = number| 

NIXL = number| 

NLOGR = number| 

NRETR = number| 

NSSS = number| 

NUPDR = number| 

PASSWD = address| 

_ RKP =aumber| 

SHRPOOL = aumber| 

STMST = address| 

STRNO = number} 
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The subparameters of the TESTCB macro can be expressed as absolute numeric 
expressions, as character strings, as codes, as expressions that generate valid 
relocatable A-type address constants, in register notation, as S-type address 
constants, and as indirect S-type address constants. Appendix C, “Operand 
Notation” on page 181, further defines these operand expressions. 


ACB= address 


specifies the address of the access method control block whose information 
you want to test. You may omit it only if you're testing the Iength of an 
access method control block (ACBLEN =numbcr). (All VSAM access 
method control blocks have the same length.) 


ERET = address 


specifies the address of a routine to which VSAM is to give control if, 
because of an error, it is unable to test for the condition you specify. For 
example, testing AVSPAC in an access method control block for an 
unopened data sect would fail. VSAM indicates in register 15 whether it 
could do the test and, if not, indicates in register 0 the rcason it couldn’t. 
(The reasons are discussed under “Control Block Manipulation Macro 
Return Codes and Reason Codes” on page 10.) A failure trying to execute 
TESTCB indicates a basic logical problem in the processing program, so 
the error routine would probably issue an ABEND. If it Icts the program 
continue, it must branch to the continuation point itself, and not return to 
VSAM. 


OBJECT = DATA|INDEX] 


specifies whether you want to test a ficld for data or for index. 


ATRB = ((ESDS][,KSDS][LDS] 


[REPL] 
.RRDS| 
[SPAN] 
LSSWD] 
L.WCKp 


specifies, for an open data set, the attribute that is to be tested for, as 
follows: 


ESDS 
entry-sequenced data set 


KSDS 
key-sequenccd data set 


LDS 
linear data set 


Note: When specified, LDS must be the only parameter indicated by 
ATRB. All other parameters will be ignored and a binary test will be 
performed that indicates whether the data set is a linear data set 
(return code 0) or not (return code 1). 
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REPL 
some portion of the index is replicated 


RRDS 
relative record data set 


SPAN 
data set contains spanned records 


SSWD 
sequence set is adjacent to the data 


WCK 
write operations for the data set are being verified 


ATRB=UNQ 
specifics, for an open alternate index or path, that the altcrnatc index 
requires uniquc keys. The test for ATRB= UNQ must be made with a 
scparate TESTCB macro. VSAM examines the path control blocks for the 
UNQ attribute; and also examines the base cluster’s control blocks for the 
other attributes. If other attributcs are tested for, VSAM cxamines the base 
clustcr’s control blocks for all attnbutes: The test for AT RB = UNQ would 
give inaccurate results when applicd to the base cluster’s control blocks. 


CATALOG = YES|NO 
specifics that a test is to be made to determine, any timc, whether or not 
the access method control block specifics a catalog data sct. 


CRA=SCRA|UCRA 
spocifies that 4 test is t0 be madc to determine, any time, whether catalog 
recovery arca control blocks are to be built in system storage or user 
storage. 


MACRE = ([ADR]], AIX]],CFX] 
L.CNV]],DDN] 
|, DFR]j,DIR} 
[,DSN}[,GSR] 
[ICI]LIN] 
|, KEY]],LSR] 
LLNCHL,NDF] 
[,NFX][,NIS] 
LNRMIL.NRS]} 
[.NSRI],NUB] 
L,OUT], RST] 
[, SEQ]LSIS] 
|, SKP]|,UBF] 


specifies that a test is to be made to determine, at any time, what 
subparameter or combination of subparameters is being used for processing. 


OFLAGS = OPEN . 
specifies that a test is to be made to determine, after open, whether the data 
set identified by the control block has been opened. 
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OPENOBJ = PATH|BASE|AIX 
specifies that a test is to be made to determine, after open, whether an 
opened object is a path, a base cluster, or an alternate index. 


The remaining parameters represent fields in an access method control block that 
can be compared with the value specified. These ficlds are the same as those that 
can be displayed by using the SHOWCB macro and are. described in Figure 14 
on page 134. 


If you omit a routine to handle error conditions, you can examine register 15 
following TESTCB by using a branch table, for example, but don’t alter the 
PSW condition code that VSAM set to indicate the result of a test until you’ve 
had a chance to test it. 


Example: TESTCB Macro (Test for Data Sct Attributes) 


In this example, a TESTCB macro is used to determine whcther a data sct is a 
key sequenced or an entry-sequenced data set. 


LIST RPL 


e 


SHOWCB AREA=DATAFACT, 


FIELDS=ACB, 
LENGTH=4, 
RPL=LIST 
LTR 15,15 
BNZ CHECKO 
TESTCB ACB=(*, Is the data set key 
DATAFACT), sequenced? 
ATRB=KSDS, 
ERET=CHECKO 
BE KEYSEQ Yes. 
KEYSEQ — Data set is key sequenced. 
CHECKO ber Display or test failed. 
DATAFACT DS F For displaying address of 
access method control 
block. 


The SHOWCB macro’s parameters are: 


e AREA and LENGTH specify a 4-byte area, DATAFACT, aligned on a 
fullword boundary, to be used for the display. 


e FIELDS and RPL specify that the address of the access method control 
block in the LIST request parameter list is to be displayed. 


The TESTCB macro’s parameters are: 
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e ACB specifies that a ficld in the access method control block, the address of 
which is located at DATAFACT, is to be tested. The SHOWCB macro put 
the address of the access method control block at DATAFACT. 


e ATRB specifics that the access method control block is to be tested to 
determine whether it is a key-sequenced data set. 


¢ ERET specifies that a routine named CIIECKO is to be given control if an 
crror occurs that makes it impossible to make the test. 


There is no necd to examine the feedback field in an EODAD routine, because it 
can be assumed to contain the end-of-data-set indication. 
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TESTCB Macro (Test Fields of an Exit List) 


The format of the TESTCB macro used to test ficlds in an exit list is: 


{abe} | TESTCB] EXLST = address 
| ,ERET = address} 
{EODAD = {0|({address}f, A[N][,L)} | 


JRNAD = {0|({address]f, AINJ[,L])} | 
LERAD = (0[({address]{,AINH,LD} | 
SYNAD = (0|(faddress|], A|N],LD} } 
|, EXLLEN = number} 





The parameters of the TESTCB macro can be expressed as absolute numeric 
expressions, as character strings, as codes, as expressions that generate valid 
relocatable A-type address constants, in register notation, as S-type address 
constants, and as indircct S-type address constants. Appendix C, “Operand 
Notation” on page 181, further defines these operand expressions. 


label 
is | to 8 characters that provide a symbolic address for the TESTCB macro. 


EXLST = address 
specifies the address of the exit list whose information you want to test. 
You may omit it only if you’re testing the maximum Iength of an exit list 
(EXLLEN=number). The TESTCB macro does not support the UPAD 
user exit. 


ERET = address 
specifics the address of a routine to which VSAM is to give control if, 
because of an error, it is unable to test for the condition you specify. For 
example, testing AVSPAC in an access mcthod control block for an 
unopencd data set would fail, VSAM indicates in register 15 whether it 
could do the test and, if not, indicates in register 0 the rcason it couldn't. 
(The reasons are discussed under “Control Block Manipulation Macro 
Return Codes and Reason Codes” on page 10.) A failure trying to execute 
TESTCB indicates a basic logical problem in the processing program, so 
the error routine would probably issue an ABEND. If it lets the program 
continue, it must branch to the continuation point itself, and not return to 
VSAM. 


EODAD = (0|([address|{,AIN][,LD} | 

JRNAD = (0|(Jaddress]],AIN][,L)} | 

LERAD = {0|(faddress|{,AINJLLD}HI 

SYNAD = (0|({address}f,A|NILL)} 
specifies the exit about which you are asking a yes-no question. If you 
code more than one parameter for an exit name, each must equal the 
corresponding value in the control block for you to get an equal condition. 
The values that can be tested are: 


0 


specifies that a test is to be made to determine whether an entry is 
provided for the exit in the exit list. 
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address 
specifies that a test is to be made to determine whether this is the 
address of the exit. Tests for an address result in an cqual, unequal, 
high, low, not-high, or not-low condition. Tests for a combination of 
an address and A, N, or L result in an equal or uncqual condition. 


A|N 
specifies that a test is to be made to determine whether an exit is 
active (A) or not active (N). Tests for A or N result in an cqual or 
uncqual condition. 


specifics that a test is to be made to determine whcther the address is 
the location of an 8-byte field containing the name of a module to be 
loaded rather than the entry point of the routine. Tests for L result in 
either an equal or unequal condition. 


EXLLEN = number 
specifies cither the maximum Iength that an cxit list can have (if you don’t 
code the EXLST parameter) or the actual Iength of the exit list indicated by 
the EXLST parameter. If you specify an exit, you may not also specify 
EXLLEN; if you specify EXLLEN, you may not also specify an exit. 


If you omit a routirie to handle error conditions, you can examine register 15 
following TESTCB by using a branch table, for example, but don’t alter the 
PSW condition code that VSAM set to indicate the result of a test until you’ve 
had a chance to test it. 


Example: TESTCB Macro (Use a Branch Table) 
In this example, a TESTCB macro is used to test whether ENDPROC is the 


routine supplicd for the EODAD cxit in the exit list EXITS, and whether the 
LODAD exit is active. A branch table is used to determine whether the test is 


successful. 
TESTCB EODAD=(ENDPROC,A) Is ENDPROC supplied and is 
EXLST=EXITS the exit active? 
B *+4(15) 


If the test was made successfully, register 15 contains 0 and the ncxt instruction is 
executed. 


B TEST1 


If it was unsuccessful, register 15 contains 4 and the next instruction is executed. 


ABEND 2,DUMP 
TEST1 BNE NO 
YES ios Yes; ENDPROC is supplied 
and active. 
NO iets ENDPROC isn't supplied, or 


the exit isn't active. 
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TESTCB Macro (Test a Request Parameter List) 


The format of the TESTCB macro to test fields in a request parameter list is: 






{labef =| TESTCB} RPL= address 
| ,ERET = address| 

{AIXFLAG = AIXPKP| 

AIXPC = number| 

FINCD = number| 

10 = COMPLETE] 

OPTCD = ({ADRI[,ARD][,ASY][, BWD] 
LCNV]{,DIR]LFKS][,FWD] | 
L.GEN][,KEQ],KEY|[,KGE],LOC] 
LLRDILMIVE],NSPIL,NUPTSEQ] 
[,SKP][,SYN],UPD)| 

ACB = address| 

AREA = address| 

AREALEN = numéber| 

ARG = address} 

ECB = address| 

FDBK = number| 

KEYLEN = number| 

MSGAREA = address| 

MSGLEN = number| 

NXTRPL = addresst 

RBA = number| 

RECLEN = number| 

RPLLEN = number| 
TRANSID = number} 


The parameters of the TESTCB macro can be expressed as absolute numeric 
expressions, as character strings, as codes, as expressions that generate valid 
relocatable A-type address constants, in register notation, as S-type address 
constants, and as indirect S-type address constants. Appendix C, “Operand 
Notation” on page 181, further defines these operand expressions. 


where: 


label 
is | to 8 characters that provide a symbolic address for the TESTCB macro. 


RPL = address 
specifies the address of the request parameter list whose information you 
want to test. You may omit it only if you're testing the length of a request 
paramcter list (RPLLEN = number). (All request paramcter lists have the 
same length.) 


ERET = address 
specifies the address of a routine to which VSAM is to give control if, 
because of an error, it is unable to test for the condition you specify. For 
example, testing AVSPAC in an access method control block for an 
unopened data set would fail. VSAM indicates in register 15 whether it 


152 MVS/XA VSAM Administration: Macro Instruction Reference 


TESTCB—RPL 


could do the test and, if not, indicates in register 0 the reason it couldn’t. 
(The reasons are discussed under “Control! Block Manipulation Macro 
Return Codes and Reason Codes” on page 10.) A failure trying to execute 
TESTCB indicates a basic logical problem in the processing program, so 
the error routine would probably issue an abend. If it lets the program 
continue, it must branch to the continuation point itself, and not return to 
VSAM. 


AIXFLAG = AIXPKP 
specifics that prime-key pointers are used rather than RBAs. 


AIXPC = number 
specifics the pointer count. 


FINCD = number 
specifies whether the upgrade set is correct or may have been modified by a 
request. These codes are described under “Component Codes 
(RPLCMPON)” on page 14. 


10 = COMPLETE 
specifics that a test is to be made to determine whcther an asynchronous 
request has.becn completed. (When you issue a CHIECK macro, you 
suspend processing until a request has becn completed if it hasn’t yet been 
completed.) 


OPTCD = (, ADR], AARD],ASY]], BWD]],CNV][,DIRI[,FKS] 
[.FWD]L,GEN],,.KEQ],KEY |, KGE]],LOC],LLRD] 
[ MVE,.NSP].NUPIL,SEQU,SKPIL,SYNILUPD] 
specifics that a test is to be made to determine what subparameter or 
combination of subparamctcrs is being used for the request. See Figure 17 
on page 184 for a description of these subparameters. 


The remaining paramcters specify ficlds 1n a request parameter list and valucs; the 
contents of a ficld are to be compared to the specified value. These fields are the 
same as those that can be displayed by using a SHIOWCB macro. (Sce Figure 15 
on page 142 for an explanation of these fields.) Fields can be tested at the same 
time they are displayed. 


You may specify only one keyword. If you code a list of option codes (for 
example, OPT'CD=(KEY,DIR)), each of them must equal the corresponding 
value in the control block for you to gct an equal condition. 


If you omit a routine to handle crror conditions, you can examinc register 15 
following TESTCB by using a branch table, for example, but don’t alter the 
PSW condition code that VSAM sct to indicate the result of a test until you've 
had a chance to test it. 
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TESTCB—RPL 


Example: TESTCB Macro (Test a Request Parameter List) 
TESTCB RPL=(3), 


RECLEN=80 
BE NOCHNGE 

CHANGE ree Because the record length in 
the request: parameter list was 
not 80, the length indicator 
must be modified so that it 
is 80 . 

NOCHNGE ... Because the record length in 


the request parameter list was 
80, no change is required. 


The TESTCB macro’s parameters are: 


¢ RPL spccifics that the address of the request parameter list to be tested is 
contained in register 3. 


e RECLEN spccifics that the record length indicated in the request parameter 
list is to be tested to determine whether it is 80. 
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VERIFY 


VERIFY Macro (Synchronize End of Data) 


The format of the VERIFY macro is: 





is 1 to 8 characters that provide a symbolic address for the VERIFY macro. 


RPL = address 
specifies the address of the request parameter list that defines this VERIFY 
request. You may specify the address in register notation (using a register 
from 1 through 12, enclosed in parentheses) or specify it with an expression 
that gencrates a valid relocatable A-type address constant. 


The following parameter and subparameter are required for VERIFY: 
In the RPL, OP TCD = (CNYV,...) must be specified. 


ACTION = REFRESH 
specifics that the VSAM control blocks are to be updated from the catalog 
after an attempt has been madc to verify the high-used RBA. For a data 
set that has been extended, VERIFY with ACTION = REFRESH will 
invoke end of volume processing to update the control block structure, 
reficcting the new extents. 


If you do not specify ACTION = REFRESH for an extended data set, you must 
close the data sct and reopen it to obtain new extent information before you can 
verify it. 


Any attempt to issue the VERIFY macro against a linear data set (LDS) will 
result in a logical error (rcturn code 253 in the feedback field of the RPL). 


After verifying a data set, positioning must be established with a POINT macro 
or with a GET macro with RPL OPTCD= DIR. 
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WRTBFR 


WRTBER Macro (Write Buffer) 


The format of the WRTBFR macro is: 





RPL = address 
specifies the address of the request parameter list that defines the WRTBFR 
request. An RPL need not be built especially for the 
WRTBFR—WRTBER may use an inactive RPL that defines other 
request(s) (GET, PUT, and so forth) for a data set that is using the 
resource pool. The following RPL paramcters have meaning for 
WRTBER: 


ACB = address 
ARG = address 
For TYPE= DRBA, the address of a 4-byte field that contains the 
a RBA to be located and written. 


ECB = address 


OPTCD = {ASY|SYN} 
WRTBER can be issued synchronously (SYN) or asynchronously 
(ASY). A CHECK or ENDREQ must be issued to synchronize an 
asynchronous WRTBER request. 


TRANSID = number 
Specifics a number from 0 to 31. 


All other RPL parameters are ignored. RPLs are assumed not to be 
chained. 


If the ACB to which the RPL is related has MACRF=GSR, the program 
that issues WRTBFR must be in supervisor state with protection key 0 to 
1 


TYPE= {ALL|CHK|DRBA|DS|LRU(percent)|TRN} 
specifies which buffers are to be written. 


Note: Before using WRTBFR TYPE=CHK|DRBAJTRN, be sure to 
release all buffers. VSAM defers processing until all buffers are released. 
For details about releasing buffers, see VSAM Administration. 


ALL 
specifies that all modified unwritten index and data buffers in each 
buffer pool in the resource pool are to be wntten. No buffers will be 
invalidated. Closing all the data sets that use a resource pool causes 
the same buffers to be wntten. 
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CHK 


WRTBFR 


is as TRN (below), but, if an error occurs in writing buffers, 
transaction IDs continue to be associated with the buffers. 
WRTBFR TYPE= CHK could be used by a checkpoint routine to 
record checkpoint information and leave buffers for which an error 
occurred as they were for continued processing. 


DRBA 


DS 


specifics that one of the data sct’s data buffers is to be written. The 
buffer to be wnitten is identified with the RBA pointed to by the RPL 
ARG address. 


specifies that, for the data set defined by the ACB to which the 
WRTBER’s RPL is related, all modificd unwnitten index and data 
buffers are to be written and all buffers are to be marked empty, 1.e., 
invalidated. Therefore, WRTBFR TYPE= DS should be issued only 
after all VSAM requests for the data sct have been quiesced. 
Otherwise, unpredictable results may occur. 


LRU (percent) 


TRN 


specifics that some of the modified buffers in each buffer pool in the 
resource pool are to be wntten. The percent is the percentage of 
buffers in each pool that are to be examined for possible writing. The 
least recently used buffers are examined. (If percent is coded in 
register notation, only registers 1 and 13 may not be used.) 


TYPE = LRU is used for writing some modified buffers, without 


fespect to a particular data set or transaction ID, to ensure that 


buffers will be available for GET area (without having to wait for 
buffers to be written). 


specifies that all buffers in a buffer pool that have been modified by 
requests with the transaction ID specified in the WRTBFR’s RPL are 
to be written. Transaction IDs are no longer associated with these 
buffers if WRTBFR completes successfully. 
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Appendix A. Format of Macros 


For casy reference, the formats of all the macros described in this book are 
repeated here in alphabetic order. 


ACB (Gencrate an Access Method Control Block at Assembly Time) 


[abel | ACB | [AM=VSAMJ 
|, BSTRNO = number] 
|, BUFND = number] 
|, BUFNI = number] 
|, BUFSP = number| 
| ,CATALOG = {YES|NO}} 
[,CRA = {SCRA|UCRA}}] 
[,DDNAME = ddname| 
{,EXLST = address] 
[. MACRF = ({ADR][,CNV][,.KEY] 
,CFXNEX] 
| DDNIDSN] 
|,DFRINDF} 
[, DIR], SEQUSKP] 
LICIINCH 
LINJLOUT] 
[, NISISIS] 
|. NRM|AIX] 
|. NRSIRST| 
| NSRILSR|GSR] 
|, NUB|UBFD} 
[, MAREA = address} 
|,MLEN = number} 
|,PASSWD = address] 
|, RMODE3! = {ALL|BUFF|CB|NONE}] 
| SHRPOOL = {0|number}| 
|, STRNO = number| 





ACQRANGE (Stage Data) 


[/abe}} ACQRANGE | RPL = address 
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BLDVRP (Build a VSAM Resource Pool) 


BLDVRP | BUFFERS = (size(number),size(number),...) 
| [FIX = ([BFR|IOB|(BFR,IOB)}] 
|, KEYLEN = length] 
[ RMODE3!1 = {ALL|BUFF|CB|NONE}| 


[{ SHRPOOL = {0|nwmber}] 

|, MODE = (24/31)] 

» TFRNO = number 

[, TYPE = (LSRJ,DATA|INDEX]|GSR}] 





CHECK (Suspend Processing) 


[/abef] CHECK | RPL= address 


CLOSE (Disconnect Program and Data) 


[/abeq CLOSE | (address{,(options)|...] 


| MODE = (24)31)] 
LTYPE=T] 





CNVTAD (Convert Address) 


[/abe]] CNVTAD | RPL = address | 


DLVRP (Delete VSAM Resource Pool) 


DLVRP | TYPE = {LSR/GSR} 
|, MODE = (24/31) 





| SHRPOOL = {0|2umber}] 


ENDREQ (Terminate a Request) 


[label ENDREQ | RPL= address 


ERASE (Delete a Record) 


\fabe} | ERASE | RPL= address 
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EXLST (Gencrate an Exit List at Assembly Time) 


[iabe} | EXLST | [AM=VSAM] 
_ | J EODAD = (address{, A|N][,LD] 
[,IOPID = (address)} 


LJRNAD = (address{,A|NILLD] 
[,LERAD = (addressf,AINILLDI 
[,SYNAD = (address|,AIN]],LD]} 
{,UPAD = (address{,A|N][,LD] 





GENCB (Gencrate an Access Mcthod Control Block at Execution Time) 


jfabeh | GENCB | BLK=ACB 
[,AM = VSAM] 
[,BSTRNO = number] 
|,BUFND = number] 
|, BUFNI = number] 
[, BUFSP = number] 
{,CATALOG = {YES|NO}] 
|, COPIES = number| 
[,CRA = {SCRA|UCRA}] 
{,DDNAME = ddname| 
| ,EXLST = address] 
[LENGTH = number] 
| ,.LOC = {BELOW|ANY}] 
|, MACRF = (ADR]I,CNVILKEY] 
[,CFX|NFX] 
[,DFRINDF] 
|, DIR], SEQ}, SKP] 
LICIINCY 
LINJLOUT] 
| NIS|SIS| 
[,.NRM|AIX] 
[,.NRS|RST] 
[, NSR|LSR] 
|, NUB|UBFD} 
1], MAREA = address} 
|, MLEN = number] 
[|,PASSWD = address] 
| RMODE3! = {ALL|BUFF|CB|NONE}] 
{, SHRPOOL = {0|nwmber}] 
|, STRNO = address] 
|, WAREA = address] 
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GENCB (Gencrate an Exit List at Execution Time) 


[label | GENCB | BLK=EXLST 
[,AM = VSAM] 
|, COPIES = number} 
|,EODAD = (address{,A|NILLDI 
LJRNAD = (addressf, AINILLDI 


[,.LENGTH = number} 

|, LERAD = (address{,A|NILLDJ] 
[,LOC = {BELOW|ANY} 
LSYNAD = (address, A|NILLDI 
],WAREA = address] 





GENCB (Gencrate a Request Parameter List at Execution Time) 


[/abe4 GENCB | BLK=RPL 

[,ACB = address] 

[,AM = VSAM] 

|, AREA = address] 

|, AREALEN = nwmber| 

[,ARG = address| 

[,COPIES = number] 

[,ECB = address} 

| ,KEYLEN = number} 

LLENGTH = number{ 

[LOC = (BELOW|ANY}] 

| MMSGAREA = address} 

[, MSGLEN = number| 

|, NXTRPL = address} 

L,OPTCD = ({(ADRICNV|KEY] 
|, DIR|SEQISKP] 
LARDILRD} 
|L.FWD|BWD] 
[ASYISYN] 
|, NSP|NUP|UPD} 
L.KEQIKGE] 
| EKSIGEN] 
[,LOCIMVED)] 

| ,RECLEN = number} 

[, TRANSID = munber} 

[, WAREA = address] 





GET (Retrieve a Record) 


[label |GET — | RPL=address 


162 MVS/XA VSAM Administration: Macro Instruction Reference 


GETIX (Retrieve an Index Record) 


[fabe] =| GETIX | RPL= address 


MNTACQ (Mount Acquire) 


[/abef MNTACQ | RPL= address 


MODCB (Modify an Access Mcthod Control Block) 


MODCB (Modify an Exit List) 


[/abe}] 


MODCB 


MODCB 


ACB = address 
[| BSTRNO = number] 
|,BUFND = number} 
| BUFNI = number| 
|, BUFSP = number} 
[CATALOG = {YES|NO}] 
1,CRA = {SCRA|UCRA}}] 
LDDNAME = ddname} 
| ,EXLST = address] 
|, MACRF = ({ADR][,CNV],KEY] 
[,CFX|NFX] 
|,DDN|DSN] 
|, DFR|NDF] 
[,DIR]},SEQU,SKP} 
LICIINCI} 
LIN OUT] 
[,.NIS|SIS] 
|, NRMJAEX] 
[,NRS|RST] 
[,NSR|LSR] 
[, NUB|UBF))| 
|, MAREA = address] 
[, MLEN = number] 
[,PASSWD = address] 
|, RMODE31 = {ALL]BUFF|CB|NONE)] 
L.SHRPOOL = number] 
|, STRNO = number] 





EXLST = address 
| ,EODAD = (address{,A|N][,L)] 
[,.JRNAD = (address, A|N]L,L)I} 


| LERAD = (address{,A|N]|,L)] 
| SYNAD = (address{,A|N]|,L)] 
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MODCEB (Modify a Request Parameter List) 


[abe | MODCB | RPL= address 

[,ACB = address] 

|, AREA = address] 

[,AREALEN = number} 

[, ARG = address| 

[,.ECB = address] 

[ ,.KEYLEN = number] 

[,.WISGAREA = address] 

[,\ISGLEN = nwnber| 

[|,.NXTRPL = address] 

[{,OPTCD = ((ADR|CNV|[KEY] 
L,ARD|LRD] 
[.FWD|BWD] 
[| DIR|SEQ|SKP] 
| ASY|SYN] 
[,NSP|NUP|UPD] 
[|,.KEQ|KGE] 
[,FKS|GEN] 
[,LOC|MVE)) 

[,RECLEN = number} 

[, FRANSID = number| 





MRKBFR (Write Buffer) 





MRKBFR | MARK = (DINVALID|XINVALID|OUT|RLS} 
RPL = address 


OPEN (Connect Program and Data) 





[label] OPEN (address|,(options)]...) 
|, MODE = (24)31)] 


POINT (Position for Access) 


[label] POINT | RPL= address | 


PUT (Store a Record) 


[label] RPL = address 
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PUTIX (Store an Index Record) 


[label | PUTIX | RPL=address | 


RPL (Generate a Request Parameter List at Assembly Time) 


ACB = address 

|,AM = VSAM] 

|, AREA = address} 

[, AREALEN = number] 

|,ARG = address| 

| ,ECB = address} 

| ,KEYLEN = number} 

[,MSGAREA = address] 

|. MSGLEN = nurmber| 

|. NXTRPL = address] 

|,OPTCD = ((ADR|CNV|KEY] 
[, DIR|SEQISKP} 
| ARDILRD| 
LEWD|BWD] 
| ASY|SYN] 
[,NSP|NUP|UPD} 
|. KEQ|KGE] 
| FKS|GEN] 
[NWAITX|WAITX] 
|, LOC|IMVED] 

| ,RECLEN = number] 

[,TRANSID = 2zumbeA 


SCHBFR | [BFRNO = number] 
RPL = address 





SCHBFR (Search Buffer) 
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SHOWCB (Display Fields of an Access Method Control Block) 


[abel | SHOWCB | ACBaddress 

»AREA = address 

s§LENGTH = number ; 

[,,OBJECT = {DATA|INDEX}] 

FIELDS = ({ACBLEN]],AVSPAC][,BFRFND] 
|, BSTRNO]|[,BUFND][,BUFN]] 
[,BUFNO][, BUFRDS]],BUFSP] 
[,CINV][, DDNAME]],ENDRBA] 

[| ERROR][,EXLSTI[,FS] 
[,HALCRBA][,KEYLEN]],LRECL] 
| ,MAREA][,MLEN][,NCIS] 

|, NDELR][,NEXCP][,NEXT] 

|, NINSR]{,NIXL][,NLOGR] 

[| ,NRETR][,NSSS][, NUIW] 

|, NUPDR}f,PASSWD]], RKP] 

|, SHRPOOL][, STMST][, STRMAX] 
[| STRNO|[,UrwW) 





SHOWCB (Display Fields of an Exit List) 


SHOWCB | AREA = address 
»§EXLST = address 
;LENGTH = number 
FIELDS = ((EODAD],EXLLEN][,JRNAD] 
— [ LERADI,SYNAD) 





SHOWCEB (Display Fields of a Request Parameter List) 


SHOWCB | AREA = address 
»LENGTH = number 
RPL = address 
FIELDS = ({ACB]],AIXPC][,AREA] 


| AREALEN][,ARG][,ECB][,FDBK] 
{,.F TNCD][, KEYLEN]], MSGAREA] 
[. MSGLEN]],NXTRPL][,RBA] 

{,RECLEN]], RPLLEN]|, TRANSID] 





166 MVS/XA VSAM Administration: Macro Instruction Reference 


TESTCB (Test a Ficld of an Access Method Control Block) 


{label} 


TESTCB | ACB= address 


| ,.ERET = address] 

| ,.OBJECT = DATA|INDEX] 

{ATRB = ((ESDS][, KSDS]], LDS][ REPL] 
| RRDS][,SPAN][,SSWD]L,WCK))| 

ATRB=UNQ 

CATALOG = {YES|NO} | 

MACREF = ((ADR]{,AIX][,CFX][,CNV][,DDN] 
{,DFR][,DIR]|,DSN}],GSRJI,ICI] 
LIN]L KEY), ESRILNCILNDF] 
[,NEX][,NIS]LNRMILNRSI],NSR] 
[, NUB],OUTY,RSTH.SEQ],SIS] 
|, SKPI,UBF))| 

OFLAGS = OPEN | 

OPENOBJ = PATH|BASE{AIX| 

ACBLEN = number| 

AVSPAC = number| 

BSTRNO = number| 

BUFND = number| 

BUFNI = number| 

BUFNO = number| 

BUFSP = number| 

CINV = number| 

DDNAME = ddname| 

ENDRBA = number| 

ERROR = number| 

EXLST = address| 

FS = manber| 

KEYLEN = number| 

LRECL = number| 

MAREA = address| 

MLEN = number| 

NCIS = number| 

NDELR = number| 

NEXCP = number| 

NEXT = number| 

NINSR = number| 

NIXL = number} 

NLOGR = number| 

NRETR = number| 

NSSS = number| 

NUPDR = number| 

PASSWD = address| 

RKP = number| 

SHRPOOL = number| 

STMST = address| 

STRNO = number} 
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TESTCB (Test a Field of an Exit List) 


[‘abe§ | TESTCB] ,EXLST = address 
[, ERET = address} 
{EODAD = (0|(faddress][, AINILLD}| 


JRNAD = (0]({address]f, A|N][,LD} | 
LERAD = {0|([{address|f,AIN][,LD} | 
SYNAD = {0]([address]{, A|NI[,LD}} 
[,.EXLLEN = nwmnber| 





TESTCB (Test a Ficld of a Request Parameter List) 


[/abed TESTCB| RPL = address 
|, ERET = address} 
{ACB = address| 
AIXFLAG = AIXPKP| 
AIXPC = number| 
AREA = address| 
AREALEN = number| 
ARG = address] 
ECB= address] 
FDBK = number| 
FINCD = nwnber| 
KEYLEN = zumber| 
_ MSGAREA = address 
MSGLEN = number} 
NXTRPL = address| 
10 =COMPLETE| 
OPTCD = ((ADRILARDIL,ASY][, BWDIL,CNV] 
|, DIR]],FKS][,FWDI[,GEN][,.KEQ] 
|, KEY|],KGE][,LOC]],LRDILIVE] 
LNSPILNUPILSEQILSKPILSYN] 
LUPD)| 
RBA = number| 
RECLEN = number| 
RPLLEN = 2wmber| 
TRANSID = number} 





VERIFY (Synchronize End of Data) 
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WRTBER (Write Buffer) 


WRTBER | RPL = address 
»TYPE= {ALL|CHK|DRBA|DS|LRU(percent)|TRN} 
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Appendix B. List, Execute, and Generate Forms of Macros 


BLDVRP, DLVRP, GENCB, MODCB, SHOWCB, and TESTCB macros build 
a parameter list describing in codes the actions indicated by the operands you 
specify and pass the list to VSAM to take the indicated action. The list, execute, 
and generate forms of BLDVRP, DLVRP, GENCB, MODCB, SHOWCEB, and 
TESTCB allow you to write reentrant programs, to share parameter lists, and to 
modify a parameter list before using it. 


Following is a brief description of the list, execute, and generate forms: 


e The list form is used to build the parameter list cither inline (referred to as a 
simple list) or in an area remote from the macro expansion (referred to as a 
remote list). Both the simple- and the remote-list forms allow you to build a 
single parameter list that can be shared. 


@ The exccutce form is used to modify a parameter list and to pass it to VSAM 
for action. 


e The gencrate form is used to duild the parameter list in a remote area and to 


pass it to VSAM for action. 


The list, execute, and gencrate forms of the BLDVRP, DLVRP, GENCB, 
MODCB, SHOWCEB, and TESTCB macros have the same format as the 
standard forms, with the exception of: 


e An additional keyword, MF 

@ Keywords that are required in the standard form may be optional in the list, 
execute, and generate forms or may not be allowed in the execute form. The 
meaning of the keywords, however, and the notation that may be uscd to 


express addresses, names, numbers, and option codes are the samc. 


The sections that follow describe the format of the MF keyword and the use of 
list, exccute, and generate forms. They also indicate the optional and invalid 


operands. 


A °, 
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List-Form Keyword 


The format of the MF keyword for the list form is: 
MF = (L|(L,address{,/abef)} 


where: 


L 
specifies that this is the list form of the macro. 


address 
specifies the address of a remote area in which the parameter list is to be 
built. The area must begin on a fullword boundary. You can specify the 
address in register notation or as an expression valid for a relocatable 
A-type address constant or a direct or indirect S-type address constant. 


label 
is a unique name that is used in an EQU instruction in the expansion of 
the macro; label is equated to the length of the parameter list. You do not 
have to know the Icngth of the parameter list if you code !abcl; the 
expansion of the macro determines the amount of storage required. 


Because the MF = L expansion docs not include executable code, register 
notation and expressions that generate S-type address constants cannot be used. 


If you code MF = L, the parameter list is built inline, which means that the 
program is not reentrant if the parameter list is modificd at execution. 


If you code MF =(L,address), the parameter list is built in the remote area 
specified, and the arca must be large enough for the parameter list. 


The size, in fullwords, of a parameter list is: 


@ For GENCB, 4, plus 3 times the number of ACB, EXLST, or RPL 
keywords specified (plus 1 for DDNAME, EODAD, JRNAD, LERAD, or 
SYNAD) 


e For MODCB, 3, plus 3 times the number of ACB, EXIST, or RPL 
keywords specified (plus 1 for DDNAME, EODAD, JRNAD, LERAD, or 
SYNAD) 


e For SHOWCEB, 5, plus 2 times the number of ficlds specified in the FIELDS 
operand 


e For TESTCB, 8 (plus | for either DDNAME, STMST, EODAD, JRNAD, 
LERAD, or SYNAD) 


If you code MF =(L,address,label), the parameter list is built in the remote area 
specified. The expansion of the macro equates label with the length of the 
parameter list. . 
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aon, 


Execute-Form Keyword 


The format of the MF keyword for the execute form is: 
MF = (E,address) 


where: 


E 
specifies that this is the execute form of the macro. 


address 
is the address of the parameter list. 


The expansion of the exccutc form of the macro results in executable code that 
causcs: 


1. A parameter list to be modified if requested 
2. Control to be passed to a routine that satisfics the request 


You may not use the execute form to add an entry to a parameter list. If you try 
to add an entry, you will receive a return code of 8 in register 15. 


Generate-Form Keyword 


The format of the MF keyword for the generate form is: 
MF = (G,address|,labe]) 


where: 


G 
specifies that this is the gencrate form of the macro. 


address 
specifics the address of a remote arca in which the parameter list is to be 
built. ‘he area must begin on a fullword boundary. 


label 
is a unique name that is uscd in an EQU instruction in the expansion of 
the macro; label is equated to the Iength of the parameter list. You do not 
have to know the length of the parameter list if you code label; the 
expansion of the macro determines the amount of storage required. 


If you code MF =(G, address), the parameter list is built in the remote arca 
specified. 


If you code MF = (G, address, label), the parameter list is built in the remote area 


specified. The expansion of the macro equates the length of the parameter list to 
label. 
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| List, Execute and Generate Formats 


List Form of BLDVRP 


Note: If FIX is specified, DLVRP must be issued by the same task that issues 
BLDVRP. STRNO is optional in the list form of BLDVRP, but, if it is not 
specified, it must be specified in the execute form. 


The format of the list form of BLDVRP is: 


BLDVRP| BUFFERS = (size(nwmber),size(number),...) 
MF =L 
[,FIX = {BFR|IOB|(BFR,IOB)}} 
[,KEYLEN = length] 


| [|,RMODE3t = {ALL|BUFF|CB|NONE}] 
| |, SHRPOOL = (0jn)] 
| [, MODE = {24]31}] 
[, STRNO = number| 
| |, TYPE = (LSR],DATA|INDEX]|GSR}| 





Exccute Form of BLDVRP 


Note: The address is the address of the parameter list built by a list form of 
BLDVRP. If you use register notation, you may use register 1, and a register 
between 2 and [2. Register [ is used fo pass the parameter list to VSAM. 
BUFFERS may not be specified in the execute form of BLDVRP, because this 
operand affects the length of the parameter list. 


The format of the execute form of BLDVRP is: 


BLDVRP| MF =(E,address) 
| ,.KEYLEN = length] 
| |, RMODE31 = {ALL|BUFF|CB|NONE}] 
| . |, SHRPOOL = number} 
| |, MODE = (24[31}] 
|, STRNO = number] | 
| |, TYPE = {LSRJ,DATA|INDEX]|GSR}] 





| Note: If MODE=31 was specificd on the list form, MODE=31 must be 
{ specified on the execute form. The same is true for MODE = 24. 
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Executec Form of DLVRP 


Note: There is no list form for DLVRP, because DLVRP works with | 
BLDVRP: It uses the parameter list associated with BLDVRP. The address is 
the address of the parameter list built by a list form of BLDVRP. If you use 
register notation, use register 1 to pass the address of the parameter list to 
VSAM. . 


| If MODE = 31 in the BLDVRP macro, then MODE = 31 is required in the 
| DLVRP macro. 


The format of the execute form of DLVRP is: 


MF = (E, address) | 
|, SHRPOOL = number} 


| |, MODE = (24131}] 
»sTYPE= ({LSR|GSR} 





List Form of GENCB 


The format of the list form of GENCB is: 


GENCB | BLK= {ACBJEXLST|RPL} 
[,AM = VSAM] 
[,COPIES = number] 
[| keyword = {address|name|number|option},...] 
{,LENGTH = number] 

| [LOC = {BELOW|ANY}] 
q | JL RMODE31 = {ALL]BUFF|CB]NONE}] 

MF = {L|(L,address{,/abef)} 
|, WAREA = address] 





Execute Form of GENCB 


The format of the execute form of GENCB is: 


[labeh | GENCB | BLK = {ACBJEXLST|RPL} 
|,AM = VSAM] 
| ,COPIES = number] 
|, keyword = {address|name|number|option)},...] 
[,.LENGTH = awnber| 
| [,.LOC = {BELOW|ANY}}] 
| |. RMODE31 = {ALL|BUFF|CB|NONE}] 
MF = (E,address) 
|, WAREA = address] 
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Gencrate Form of GENCB 


The format of the generate form of the GENCB macro is: 


[label GENCB | BLK={ACB|EXLST|RPL} 
[AM=VSAM] 
[,COPIES = number} 
| keyword = address|name|number|option},...] 


[,LENGTH = mwunber| 

[,LOC = (BELOWJANY}}] 

[,RMODE3!1 = {ALL|BUFF|CB|NONE}] 
yMF = (G,address{,labef) 

[,WAREA = address| 





List Form of MODCB 


The format of the list form of MODCB is: 


[label | MODCB} {ACBJEXLST|RPL{ = address 


keyword = {address|name|number|option}.,... 


MF = {L|(L,address{,/abef])} 





Execute Form of MODCB 


Note: If the execute form of MODCB is used and EXLST is used as a keyword 
to be processed, the block must be identified by ACB=. 


The format of the execute form of MODCB is: 


[labe} =| MODCB| [{ACB|EXLST|RPL} = address] 


keyword = {address|name|number|option},... 
»MF = (E,address) 





Gencrate Form of MODCB 


The format of the generate form of MODCB is: 


[/abel] MODCB | {ACBJEXLST|RPL{ = address 


keyword = {address|name|number|option},... 
IMF = (G,address|,label}) 
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List Form of SHOWCB 


The format of the list form of SHOWCB is: 


[/abel. | SHOWCB | [{ACB|EXLST|RPL)} = address 


AREA = address 
FIELDS = (keyword],keyword,...]) 
sLENGTH = number 

MF = {L|(L,address{,labe])} 
OBJECT = (DATA|INDEX}] 





Exccute Form of SHOWCB 


The format of the execute form of SHOWCB is: 


[/abel SHOWCEB | [{ACBJEXLST|RPL} = address 
AREA = address 
»MF = (E,address) 
OBJECT = {DATA|[INDEX}] 





Gencrate Form of SHOWCB 


The format of the generate form of SHOWCB is: 


[label] SHOWCB | [{ACB|EXLST|RPL} = address] 
AREA = address 
sFIELDS = (keyword|,keyword.,...]) 
LENGTH = number 
»MF = (G,address|,labef}) 
[OBJECT = {DATA|INDEX}] 





List Form of TESTCB 


Note: If the execute form of TESTCB is used and EXLST is used as a keyword 
to be processed, the block must be identified by ACB=. 


The format of the list form of TESTCB 1s: 


‘TESTCB | [{ACB|EXLST|RPL) = address| 
{,ERET = address] 


keyword = {address|name|number|option},... 
MF = {L|(L,address{,/abef)} 
[OBJECT = {DATA|[INDEX}] 
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Execute Form of TESTCB 


Note: If the execute form of TESTCB is used and EXLST is used as a keyword 
to be processed, the block must be identified by ACB=. 


The format of the execute form of TESTCB is: 


TESTCB | [{ACB|EXLST|RPL)} = address] 


[,.ERET = address} 

keyword = {address|name|number|option)},... 
»NIF = (E,address) 

[OBJECT = {DATA|INDEX}] 





Generate Form of TESTCB 


The format of the gencrate form of TESTCB is: 


TESTCB | [{ACB|EXLST|RPL} = address} 
| ,ERET = address} 


keyword = {address|name|number|option},... 
VIF = (G,address{,labef}) 
,,OBJECT = {DATA|INDEX}] 





Use of List, Execute, and Generate Forms 


Figure 16 indicates which forms of GENCB, MODCB, SEIOWCB, and 
TESTCB should be used in reentrant/nonreentrant and shared/nonshared 


environments. 

Reentrant Nonreentrant 
Shared MF =(L,address{,/abel}) MF=L 

MF = (E, address) MF = (E, address) 


Nonshared ME =(G,address{,/abel]) Standard Form 


Figure 16. Rceentrant Programming 


The figure shows that: 


e To share paramcter lists in a reentrant program, the remote- list form should 
be used in conjunction with the execute form. 


e To share. parameter lists in a nonreentrant program, the simple-list form 
should be used in conjunction with the execute form. 
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e If you do not intend to share parameter lists, the generate form should be 
used in reentrant programs and the standard form should be used for 
nonrecntrant programs. 


Examples of Generate, List, and Execute Forms in Reentrant Environments 


The examples that follow illustrate how the list, execute, and generate forms 
work. 


Example: Generate Form (Reentrant) 


In this example, the generate form of GENCB is used to create a default request 
paramcter list (RPL) in a reentrant environment. 


LA 10, LEN1 Get length of the parameter list. 

GETMAIN R,LV=(10) Get storage for the area in which 
the parameter list is to be built. 

LR 2,1 Save address of parameter-list 
area. 

GENCB BLK=RP 

MF=(G, (3), LEN1) 

The macro expansion equates LEN] to the Iength of the parameter list, as 

follows: 

+LEN1 EQU 16 


The parameter list will be built in the area acquired by the GETMAIN macro 
and pointed to by register 2. This list is used by VSAM to buiid the RPL. 
VSAM returns the RPL address in register 1 and the RPL Iength in register 0. If 
the WAREA and LENGTH parameters are used, the RPL will be built at the 
WARLA address. 


Example: Remote-List Form (Reentrant) 


In this example, the remote-list form of MODCB is used to build a parameter list 
that will later be used to modify the MACRF bits in the access method control 


block ANYACB. 

LA 8, LEN2 Get length of the parameter 
list. .: 

GETMAIN’ R,LV=(8) Get storage for the area in 
which the parameter se is to 
be built. 

LR es Save address of the 


parameter-list area. 


MODCB ACB=ANYAC 
HACRMF=(L_ (3), LEN2) 


The macro expansion equates the length of the parameter list to LEN2, as 
follows: 


+LEN2 EQU 24 
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This parameter list is built in the remote area pointed to by register 3. The list 
will be used by VSAM to modify the ACB when an execute form of MODCB is 
issued (see next example). The list form only creates a parameter list; it does not 
modify the ACB. 


Example: Execute Form (Reentrant) 


In this example, the execute form of MODCB is used to modify the address of 
the access method control block and MACRF codes in the parameter list created 
by the remote-list form of MODCB in the previous example. 


MODCB ACB=MYACB,MACRF=(ADR, SEQ, OUT) ,MF=(E,(3)) 


The parameter list pointed to by register 3 is changed so that the ACB and 
MACREF parameter values in the execute form override those in the list form. 
The access method control block, MYACB, is then modified to 

MACRF =ADR,SEQ,OUT). The access method control block at ANYACB is 
not changed by either of these examples. 
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Appendix C. Operand Notation 


Operands with GENCB, MODCB, SHOWCB, and TESTCB 


The addresses, names, numbers, and options required with operands in GENCB, 
MODCB, SITOWCB, and TESTCB can be expressed in a variety of ways: 


An absolute numeric expression, for example, STRNO = 3 and COPIES = 10. 


A code or a list of codes separated by commas and enclosed in parentheses, for 
example, OPTCD= KEY or OPTCD=(KEY,DIR,IN). 


A character string, for example, DDNAME= DATASET. 


A register from 2 through 12 that contains an address or numeric value, for 
example, SY NAD = (3); equated labels can be uscd to designate a register, for 
example, SYNAD=(ERR), where the following equate statement has been 
included in the program: ERR EQU 3. 


An expression of the form (S,scon), where scon is an expression valid for an 
S-type address constant, including the base-displacement form. The contents 
of the base register will be added to the displacement to obtain the value of 
the keyword. For example, if the value of the keyword being represented is a 
numenic value (that is, COPIES, LENGTH, RECLEN), the contents of the 
base register will be added to the displacement to determine the numeric 
value. If the value of the keyword being represented is an address constant 
(that is, WAREA, EXLST, EODAD, ACB), the contents of the base register 
will be added to the displacement to determine the value of the address 
constant. 


An expression of the form (*,scon), where scon is an expression valid for an 
S-type address constant, including the base-displaccment form; the address 
specificd by scon is indirect, that is, it is the address of an area that contains 
the value of the keyword. The contents of the base registcr will be added to 
the displacement to determine the address of the fullword of storage that 
contains the value of the keyword. 


If an indirect S-type address constant is used, the value it points to must meet 
the following criteria: 


— If it is a numeric quantity or an address, it must occupy a fullword of 
storage. 
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— If it is an alphameric character string, it must occupy two words of 
storage, be left aligned, and be filled on the nght with blanks. 


e An expression valid for a relocatable A-type address constant, for example, 
AREA= MYAREA + 4. 


The specified keyword determines the type of expressions that can be used. 
Additionally, register and S-type address constants cannot be used when MF = L 
is specified. 


The tables containing the individual macro operand notations have been deleted 
from this release. This information may be obtained from the individual macro 
_ descriptions shown in Chapter 2, “VSAM Macro Formats and Examples”. 
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Appendix D. Building Parameter Lists 


The standard forms of GENCB, MODCB, SHOWCB, and TESTCB build a 
parameter list, put its address in register 1, and pass control to a VSAM routine 
to generate, modify, display, or test an access method control block, exit list, or 
request parameter list. Other forms of the macros only build the parameter list 
(list forms) or only pass control to VSAM (execute forms). 


You can avoid using a macro to build the parameter list by building it yourself 
and issuing the execute form of the macro to pass control to VSAM. This 
chapter explains how to build the parameter lists for GENCB, MODCB, 
SHOWCB, and TESTCB. The rules for combinations of codes in a paramcter 
list are the same as the rulcs for combinations of operands in a macro. 


You can avoid issuing the execute form of the macro by coding the linkage 
instructions that pass control directly to the VSAM control block manipulation 
routine. Before passing control, you must build the paramcter list yourself. 


The Format of the Parameter Lists 


A paramcter list for GENCB, MODCB, SHOWCEB, or TESTCB is a list of 
fullword addresses. The first address points to a header entry that idcntifics the 
type of request and type of control block and gives other general information 
about the request. Each of the rest of the addresses in the parameter list points 
to an element entry that identifies the information you want to generate, modify, 
display, or test. 


The fullwords in the paramcter list must be contiguous, and the last one must 
have a | in its first bit. The header entry and each element entry may be separate 
from each other. Figure 17 on page 184 gives the formats of the hcadcr and 
element entries for the four request types. 
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Header Entry 


Genenusa GENFTC | GENCOP 


GENCB 


Control Function Number of copies 
block type | type of block 


GENUSA (optional) 


Address of area provided 
for generation 


GENUSL (optional) (reserved) 


Length of area 


Modification MODBTC MODFTC (reserved) 


MODCB Control- Function 


block type type 


MODBLAD 


Address of control block 
to be modified 


Display SHOWBTC |SHOWFTC |SHOWOBS 


SHOWCB (optional) 


Control- Function Object type 
block type type (data or index) 


SHOWBLAD (optional) 


Address of control 
block to be displayed 


SHOWUSA 


Address of area provided 
for display 


SHOWUSL (reserved) 
Length of area 


Test TESTBTC TESTFTC TESTOBS 


TESTCB (optional) 


Controk Function Object type 
block type type (data or index) 


TESTBLAD (optional) 


Address of control 
block to be tested 


TESTERET (optionat) 


Address of error-analysis 
routine (ERET) 


(reserved) 











Element Entry. 


Of ELEMKWTC (reserved) 
Keyword 
type 











| (required for | 

| some keywords)* | 

L —_m Se oR ewes oo —_——PD ee owe EE oD ——— d 
Of ELEMKWTC 







Keyword 
type 
4 
Keyword value 
| 
(required for | 
| some keywords)* ] 
Ge ea acters: Seca, sions, “ema” cae, > cf nai ad 
OfELEMKWTC 


Keyword 


type 


Of ELEMKWITC 


Keyword 
type 





Keyword value 


8 
| (required for | 
| some keywords)* | 
a ea ee J 


*Second fullword required for 
keyword value of DDNAME, . 
STMST, EODAD, JRNAD, 
LERAD, and SYNAD. 


Figure 17. Format of Header and Element Entries for GENCB, MODCB, SHOWCB, and TESTCB Parameter Lists 
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Building Header and Element Entries 


Five assembler macros are provided for building entries. 

IDAGENC, IDAMODC, IDASHOW, and IDATEST help you build a header 
entry for generation, modification, display, or test. IDAELEM helps you build 
an element entry. 


IDAGENC | IDSECT = {YESINO}| 
[label [DSECT = {YES|NO}] 
[DSECT = {YES|NO}] 

[DSECT = {YESINO}| 


DSECT = {YES|NO} 
Indicates whether a DSECT statement is to be generated. If you intend to 
build entrics in a continuous arca, you could have only the first of the 
macros gencrate a DSECT statement and use a single register to address the 
whole areca. 



























These macros gencrate labeled DS statements that give the layout of an entry and 
EQU statements that equate a label with a numeric code. You can symbolically 
encode an entry with a series of move instructions. ‘The macros arc 
self-documenting— inspect a listing of their expansions and you can see which 
labels to code in your move instructions. (You can list the macros as they 
appear in the macro library.) 


To gencrate an exit list with LEKAD and SYNAD exits, you could code a 
GENCB of the standard form: 

GENCB BLK=EXLST, LERAD=(LOGERR, L) ,SYNAD=PHYSERR 

The following example shows how to achieve the same effect by building the 


parameter list and entries yourself and issuing a GENCB of the execute form. 


LA 5 ,NTRYAREA Set up base register for 
the entries. 


USING 5 ,GENC GENC is the first label in 
the work area. 


Build the list of addresses that point to the entries. 


ST 5,PLIST Address of the header 
entry. 
LA 6,GENLEN(,5) Address of the first 


element entry. GENLEN is 
equated to the length of 
a header element for 
generation. 


ST 6, PLIST+4 
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LA 


ST 

or 
Build the header 

MVI 


MVI 


MVI 


ST 


Build the second 


LA 


ST 
MVI 


6, ELEMLLEN( , 6) 


6, PLIST+8 
PLIST+8,X'80' 
entry. 
GENBTC , GENXLST 


GENFTC , GENFTYP 


GENCOP+1,X'01' 


ELEMKWTC#1, 
ELEMLEAD 


6, LOGERR 


6,ELEMPTR 
ELEMXFLG, 


ELEMXL+ELEMXADR . 


element entry. 


5 , ELEMLLEN( , 5) 


ELEMKWTC+1, 
ELEMSYAD 


6, PHYSERR 


6, ELEMPTR 


ELEMXFLG, 
ELEMXADR 


Pass control to VSAM. 


GENCB 
LTR 
BNZ 


MF=(E , PLIST) 
15,15 
CHECKO 
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Address of the second 
element entry. ELEMLLEN 
is equated to the length 
of an element entry for 
an exit list. 


End-of-list indicator. 


Indicate the 
blocktype-exit list. 


Indicate the function 
type-generation. 


Indicate the number of 
copies of the exit list 
to be generated. 


ea the keyword type- 


Address of the name of the 
logical error analysis 
module. 


Indicate the presence of 
an. address ELEMPTR and 
that the exit routine is 
to be loaded. 


Align the DSECT with the 
second element entry. 
ELEMLLEN is equated to the 
length of an element entry 
for an exit list. 


Indicate the keyword 
type-SYNAD. 


Address of the entry point 


of the physical error 
analysis routine. 


Indicate the presence of 


an address in ELEMPTR. 


Generation successful? 


No. 


CHECKO ABEND 1,DUMP Register 0 indicates the 
error. 


Physical error analysis exit routine. 
PHYSERR .. . 
Work areas and constants. 


LOGERR DC CL8' LEMOD' Name of the 
logical error analysis 
module to be loaded. 


PLIST DC 3F'0' List of entry addresses. 
3 addresses are 
required: 1 for the header 
and 2 for the elements 
(1 for LERAD and 1 for 


SYNAD). 
NTRYAREA DC 9F'O' Work area for header and 
, element entries. The 


header for GENCB is 3 
fullwords, and so are 
the LERAD and SYNAD 
elements. 


DSECT with labels for the header and element entries. 


IDAGENC Header entry. A DSECT 
statement is generated, 
and register 5 is used 
to address NTRYAREA 
with these labels. 


IDAELEM DSECT=NO Element entry. Element 
labels are part of the 
same DSECT as the 
header labels. 


Passing Control Directly to VSAM 


You can avoid using the execute form of GENCB, MODCB, SHOWCB, and 
TESTCB by building your own linkage instructions. You first build a parameter 
list, as described in the previous section, and put its address in register 1. Then 
you pass control to VSAM using the following instructions: 


L 15,16 Put. the address of the CVT 
into register 15. 

L 15,256(,15) Put the address of the AMCBS 
control block into register 15. 

L 15,12(,15) Put the address of the control 


block manipulation routine into 
register 15. 
BALR 14,15 Branch to the routine 


The BALR 14,15 instruction is used when the specific function (GENCB, 
MODCB, SHOWCEB, or TESTCB) is not known, or when the control block 
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type (ACB, EXLST, or RPL) is not known. The user-built parameter list 
contains the function code and control block type code. 


Decimal 

Value of xx Function Control Block 

8 GENCB ACB 

12 GENCB RPL 

16 GENCB EXLST 

20 Reserved 

24 MODCB ACB 

28 MODCB RPL 

32 MODCB | EXLST 

36 Reserved 

40 SHOWCB ACB 

44 SHOWCB RPL 

48 SHOWCB EXLST 

52 Reserved 

56 TESTCB ACB 

60 TESTCB RPL 

64 TESTCB EXLST 

68 Reserved 

72 SHOWCB or Block length 
TESTCB keywords only 

76! SHOWCB RECLEN field 

of an RPL 
80! MODCB RECLEN field 
of an RPL 


' Register | points to an RPL when xx is 76 or 80. Sce the following scction 
for details. 


When VSAM retums to your program, register 15 contains a completion code. 
Register 15 contains a zero value if the task completed successfully. Otherwise, 
register 15 and register 0 contain codes that identify the reason VSAM could not 
complete the task. 


Modifying and Displaying the RECLEN Field of an RPL Directly 


You can modify or display the RECLEN field (that is, the record length) of an 
RPL without issuing a SHIOWCB or MODCB macro, and without building a 
parameter list. 


To modify a RPL’s RECLEN ficld, you first put the address of the RPL in 
register 1, and the value to be set in the RECLEN ficld in register 0. Next, you 
code the instructions that put the address of the VSAM control block 
manipulation routine into register 15, then branch to the routine: 
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L 15,16 Put the address of the CVT into 
register 15. 


L 15,256(,15) Put the address of the AMCBS 
control block into register 15. 


L 15,12(,15) Put the address of the control 
block manipulation routine 
into register 15. 


BAL 14,80(,15) Branch to the routine. 


When VSAM returns to your program, register 15 contains a complction code. 
Reyister 15 contains a zero value if the field was modified correctly. Otherwise, 
register 15 and register 0 contain codes that identify the reason VSAM could not 
complete the task. 


To display the contents of a RPL’s RECLEN field, you first put the address of 
the RPL in register 1. Next, you code the instructions that put the address of the 
VSAM control block manipulation routine into register 15, and then branch to 
the routine: . 


L 15,16 Put the address of the CVT into 
register 15. 
L 15,256(,15) Put the address of the AMCBS 


control block into register 15. 


L 15,12(,15) Put the address of the control 
block manipulation routine into 
register 15. 


BAL 14,76(,15) Branch to the routine. 


When VSAM returns to your program, register 15 contains a complction code. 
Register 15 contains a zero value if the field 1s displayed correctly, and register 0 
contains the valuc of the RPL’s RECLEN field. When register 15 1s not zero, 
register 15 and register 0 contain codes that identify the reason VSAM could not 
complete the task. 
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Glossary of Terms and Abbreviations 


The following terms are defined as they are used in this 
book. If you do not find the term you are looking for, 
see the index or the /BM Vocabulary for Data 
Processing, Telecommunications, and Office Systems, 
GC20-1699. 


ACB. (See access method control block.) 


access method control block. A control block that links 
an application program to VSAM or ACF/VTAM. 


access method services. A multifunction service 
program that is used to define VSAM data sets and 
allocate space for them, convert indexed-scquential data 
sets to key-sequenced data scts, modify data set 
attributes in the catalog, reorganize data scts, facilitate 
data portability between operating systems, create 
backup copies of data sets, help make inaccessible data 
sets accessible, list the records of data scts and catalogs, 
define and build alternate indexes, and convert OS 
CVOLSs and VSAM catalogs to integrated catalog 
facility catalogs. 


acquire. To allocate space on a staging drive and to 
stage data from an MSS cartridge to the staging drive. 


addressed-direct access. The retrieval or storage of a 
data record identified by its RBA, independent of the 
record's location relative to the previously retrieved or 
stored record. (See also keyed-direct access, addressed- 
sequential access, and keyed-sequential access.) 


addressed-sequential address. The retrieval or storage of 
a data record in its entry sequence relative to the 
previously retrieved or stored record. (See also 
kcyed-scquential access, addressed-direct access, and 
keyed-direct access.) 


altcrnate index. A collection of index entries organized 
by the alternate keys of its associated base data records. 
It provides an alternate means of locating records in the 
data component of a cluster on which the alternate 
index is based. 


alternate index cluster. The data and index components 
of an alternate index. 


alternate key. One or more consecutive characters 
taken from a data record and used to build an alternate 


index or to locate one or more base data records via an 
alternate index. (See also generic key, key, and key 
field.) 


APF. (See authorized program facility.) 


application. As used in this publication, the use to 
which an access method is put or the end result that it 
serves; contrasted to the internal operation of the access 
method. 


authorized program facility. A facility that permits the 
identification of programs that are authorized to use 
restricted functions. 


base cluster. A key-sequenced or entry-sequenced data 
set over which one or more alternate indexes are built. 


base RBA. The RBA stored in the header of an index 
record that is used to calculate the RBAs of data or 
index control intervals governed by the index record. 


catalog. (See mastcr catalog and user catalog.) 


catalog recovery area. An entry-sequenced file that 
exists on cach volume owned by a recoverable catalog, 
including the catalog itself. The CRA contains records 
that are duplicates of the catalog entries describing the 
volume and the files it contains. 


CBIC. Control blocks in common, a facility that allows 
a user to open a VSAM data set so the VSAM control 
blocks are placed in the common service area (CSA) of 
the MVS operating system. This provides the capability 
for multiple memory accesses to a single VSAM control 
structure for the same VSAM data set. 


chained RPL. (See RPL string.) 

CI. (See control interval.) 

CIDF. (Seé control interval definition field.) 

cluster. A named structure consisting of a group of 
related components (for example, a data component 
with its index component). A cluster may consist of a 


single component. (See also base cluster and alternate 
index cluster.) 
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collating sequence. An ordering assigned to a set of 
items, such that any two sets in that assigned order can 
be collated. 


component. A named, cataloged collection of stored 
records. A component, the lowest member of the 
hierarchy of data structures that can be cataloged, 
contains no named subsets. 


control area. A group of control intervals used as a unit 
for formatting a data sct before adding records to it. 
Also, in a key-sequenced data set, the set of control 
intervals pointed to by a sequence-set index record; used 
by VSAM for distributing free space and for placing a 
sequence-set index record adjacent to its data. 


control area split. .The movement of the contents of 
some of the control intervals in a control area to a 
newly created control area, to facilitate the insertion or 
lengthening of a data record when there are no 
remaining free control intervals in the original control 
area. 


control interval. A fixed-length arca of auxiliary storage 
space in which VSAM stores records. It is the unit of 
information transmitted to or from auxiliary storage by 
VSAM. 


control interval access. The retrieval or storage of the 
contents of a control interval. 


control interval definition field. In VSAM, the 4-byte 
control information ficld at the end of a control interval 
that gives the displacement from the beginning of the 
control interval to free space and the Iength of the free 
space. If the length is 0, the displacement is to the 
beginning of the control information. 


control interval split. The movement of some of the 
stored records in a control interval to a free control 
interval, to facilitate the insertion or lengthening of a 
record that won’t fit in the original control interval. 


control volume. A volume that contains one or more 
indexes of the catalog. 


CRA. (See catalog recovery area.) 


cross memory. A synchronous method of 
communication between address spaces. 


CVOL. (See control volume.) 
DASD. (See direct access storage device.) 
data record. A collection of items of information from 


the standpoint of its use in an application, as a user 
supplies it to VSAM for storage. 


data set. The major unit of data storage and retrieval 
in the operating system, consisting of data in a 
prescribed arrangement and described by control 
information to which the system has access. As used in 
this publication, a collection of fixed- or variable-length 
records in auxiliary storage, arranged by VSAM in key 
sequence or in entry sequence. (See also key-sequenced 
data set and entry-sequenced data set.) 


DD statement. data definition statement 


direct access. The retrieval or storage of data by a 
reference to its location in a data set rather than rclative 
to the previously retrieved or stored data. (See also 
addressed-direct access and kcyed-direct access.) 


direct access storage device. A device in which the 
access time is cffectively independent of the location of 
the data. 


EBDIC. Extended binary-coded decimal interchange 
code. A coded character set consisting of 8-bit coded 
characters. 


entry sequence. The order in which data records are 
physically arranged (according to ascending RBA) in 
auxiliary storage, without respect to their contents. 
(Contrast with key sequence.) 


entry-sequenced data sct. A data set whose records are 
loaded without respect to their contents, and whose 
RBAs cannot change. Records are retricved and stored 
by addressed access, and new records are added at the 


_ end of the data set. 


EOD. end of data 
EOKR. end-of-key range 
EQOV. end of volume 


field. In a record or a control block, a specified area 
used for a particular category of data or control 
information. 


free control interval pointer list. In a sequence-sct indcx 
record, a vertical pointer that gives the location of a free 
control interval in the control area governed by the 
record. 


free space. Space reserved within the control intervals 
of a key-sequenced data set for inserting new records 
into the data set in key sequence; also, whole control 
intervals reserved in a control area for the same 
purpose. 


GENDSP. An option of LOCATE to obtain the 
control interval number of the catalog record of each 
object. 
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generation data group. A collection of data sets that are 
kept in chronological order; each data set is called a 
generation data set. 


gencric key. A high-order portion of a key, containing 
characters that identify those records that are significant 
for a certain application. For example, it might be 
desirable to retrieve all records whose keys begin with 
the generic key AB, regardless of the full key values. 


global shared resources. An option for sharing 1;0 
buffers, 1;O-rclated control blocks, and channel 
programs among VSAM data scts in a resource pool 
that serves all address spaces in the system. 


GSR. (See global shared resources.) 


header, index record. In an index record, the 24-byte 
ficld at the beginning of the record that contains control 
information about the record. 


header entry. In a parameter list of GENCB, MODCB, 
SHIOWCB, or TESTCR, the entry that identifies the type 
of request and control block and gives other gencral 
information about the request. 


horizontal pointer. In the header of an index record, the 
RBA of the index record in the same level as this one 
that contains keys next in ascending sequence after the 
keys in this one. 


index. As used in this publication, an ordered collection 
of pairs, cach consisting of a key and a pointer, used by 
VSAM 40 sequence and locaie the records of 4 
key-sequenced data set. 


index level. A set of index records that order and give 
the location of all the control intervals in the next lower 
level or in the data set that it controls. 


index record. A collection of index entries that are 
retrieved and stored as a group. (Contrast to data 
record.) 


index record header. In an index record, the 24-byte 
ficld at the beginning of the record that contains control 
information about the record. 


index replication. The use of an entire track of dircct 
access storage to contain as many copies of a single 
index record as possible; reduces rotational dclay. 


index sct. The set of index Ievels above the sequence 
set. The index set and the sequence set together 
comprise the index. 


integrated catalog facility. The name of the catalog 
associated with the Data Facility Product program 
product. 


1OPID. 1/0 prevention identifier which is used to 


- terminate I/O and prevent new I/O from being started. 


ISAM. indexed sequential access method 


ISAM interface. A set of routines that allow a 
processing program coded to use ISAM (indexed 
sequential access method) to gain access to a 
key-sequenced data set. 


JCL. (See job control language.) 


job catalog. A catalog made available for a job by 
means of the JOBCAT DD statement. 


job contro! language. A problem-oricnted language 
designed to express statements in a job that are used to 
identify the.job or describe its requirements to an 
operating system. 


job step catalog. A catalog made available for a job by 
means of the STEPCAT DD statement. 


key. One or more characters within an item of data 
that are used to identify it or control its use. As used in 
this publication, one or more consecutive characters 
taken from a data record, used to identify the record 
and establish its order with respect to other records. 
(See also key ficld and gencric key.) 


key field. A ficld located in the same position in each 
record of a data sect, whose contents are used for the key 
of a record. 


key sequence. The collating sequence of data records, 
determined by the value of the key field in each of the 
data records. May be the same as, or different from, 
the entry sequence of the records. 


key-sequenced data set. A VSAM file (data set) whose 
records are loaded in key sequence and controlled by an 
index. Records are retrieved and stored by keyed access 
or by addressed access, and new records are inserted in 
key sequence by means of distributed free space. 
Relative byte addresses of records can change because 
of control interval or contro! arca splits. 


keycd-direct access. The retrieval or storage of a data 
record by use of cither an index that relates the record's 
key to its relative location in the data set or a relative 
record number, independent o1 the record's location 
rclative to the previously retricved or stored record. 
(See also addresscd-direct access, keyed-scquential 
access, and addressed-sequential access.) _ 


keyed-sequential access. The retrieval oPstorage ofa 
data record in its key or relative record sequence relative 
to the previously retrieved or stored record, as defined 
by the sequence set of an index. (See also 
addressed-sequential access, keyed-direct access, and 
addressed-direct access.) 
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level number. For the index of a key-sequenced data 
set, a binary number in the header of an index record 
that indicates the index level to which the record 
belongs. 


linear data set (LDS). A named linear string of data, 
stored in such a way that it can be retrieved or updated 
in 4096 byte units. An LDS object is essentially a 
VSAM entry-sequenced data set that is processed as a 
control interval. Hlowever, unlike a control interval, an 
LIDS contains data only, that is, it contains no record 
definition fields (RIDFs) or control interval definition 
fields (CID Fs). 


local shared resources. An option for sharing I/O 
buffers, L;O-related control blocks, and channel 
programs among VSAM data sets in a resource pool 
that serves one partition or address space. 


LDS. (See linear data set) 
LSR. (See local shared resources.) 


master catalog. A catalog that contains extensive data 
set and volume information that VSAM requires to 
locate data sets, to allocate and deallocate storage space, 
to verify the authorization of a program or operator to 
gain access to a data set, and to accumulate usage 
statistics for data sets. 


operating system. Software that controls the exccution. 
of programs; an opcrating system may provide services 
such as resource allocation, scheduling, input/output 
control, and data management. 


password. A uniquc string of characters stored in a 
catalog that a program, a computer operator, or a 
terminal user must supply to mect security requirements 
before a program gains access to a data set. 


path. A named, logical cntity composed of one or more 
clusters (an alternate index and its base cluster, for 
example). 


physical record. A physical unit or recording on a 
medium. For example, the physical unit between 
address markers on a disk. 


pointer. An address or other indication of location. 
For example, an RBA is a pointer that gives the relative 
location of a data record or a control interval in the 
data set to which it belongs. 


prime index. The index component of a key-sequenced 
data set that has one or more alternate indexes. (See 
also index and alternate index.) 


prime key. (See key.) 


QSAM. (See queued sequential access method.) 


queued sequential access method. An extended version 
of the basic sequential access method (BSAM). When 
this method is used, a queue is formed of input data 
blocks that are awaiting processing or output data 
blocks that have been processed and are awaiting 
transfer to auxiliary storage or to an output device. 


RACF. Resource Access Control Facility. 
random access. (See direct access.) 


RBA. Relative byte address. The displacement 
(expressed as a fullword binary integer) of a data record 
or a control interval from the beginning of the data set 
to which it belongs; independent of the manner in which 
the data set is stored. 


RDF. (See record definition field.) 
record. (See index record, data record.) 


record definition ficld. A ficld stored as part of a stored 
record segment, it contains the control information 
required to manage stored record segments within a 
control interval. 


relative byte address. (See RBA.) 


relative record data set. A data set whose records are 
loaded into fixed-fength slots. 


relative record number. A number that identifies not 
only the slot, or data space, in a relative record data set 
but also the record occupying the slot. Used as the key 
for keyed access to a relative record data set. 


replication. (See index replication.) 


request parameter list. A control block that contains 
the information necded to process an 1,O request. 


resource pool, VSAM. (See VSAM resource pool.) 


reusable data set. A VSAM data set that can be reused 
as a work file, regardicss of its old contents. Must not 
be a base cluster. 


RPL. (See request parameter list.) 


RPL string. A set of chained RPIs (the set may 
contain one or more RPLs) used to gain access to a 
VSAM data set by action macros (GET, PUT, etc). 
Two or more RPL strings may be used for concurrent 
direct or sequential requests made from a processing 
program or its subtasks. 


SAM. (See sequential access method.) 


security. (See data security.) 
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sequence checking. The process of verifying the order 
of a set of records relative to some field’s collating 
sequence. 


sequence set. The lowest level of the index of a 
key-sequenced data set; it gives the locations of the 
control intervals in the data set and orders them by the 
key sequence of the data records they contain. The 
sequence set and the index set together comprise the 
index. 


sequential access. The retricval or storage of a data 
record in either its entry sequence, its key sequence, or 
its relative record number sequence, relative to the 
previously retrieved or stored record. (See also 
addressed-scquential access and keyed-sequential 
access.) 


sequential access method. An access mcthod for storing 
or retricving data blocks in a continuous sequence, using 
either a sequential access or a direct access device. 


shared resources. A sct of functions that permit the 
sharing of a pool of I;O-related control blocks, channel 
programs, and buffcrs among several VSAM data sects 
open at the same time. 


skip-sequential access. Keyed-sequential retrieval or 
storage of records here and there throughout a data set, 
skipping automatically to the desired record or collating 
position for insertion: VSAM scans the sequence sect to 
find a record or a collating position. Valid for 
processing in ascending sequences only. 


slot. For a relative record data set, the data area 
addressed by a relative record number which may 
contain a record or be empty. 


spanned record. A logical record whose length exceeds 
control interval length, and as a result, crosses, or spans, 
one or more control interval boundaries within a single 
control area. 


SRB. Service request block. A system control block 
used for dispatching tasks. 


step catalog. A catalog madc available for a step by 
means of the STEPCAT DD statement. 


terminal monitor program. In TSO, a program that 
accepts and interprets commands from the terminal, and 
causes the appropriate command processors to be 
scheduled and executed. 


time sharing option. An optional configuration of the 
operating system that provides conversational time 
sharing from remote stations. 


TMP. (See terminal monitor program.) 


transaction ID. A number associated with each of 
several request parameter lists that define requests 
belonging to the same data transaction. 


TSO. (See time sharing option.) 


update number. For a spanned record, a binary 
number in the second RDF of a record segment that 
indicates how many times the segments of a spanned 
record should be equal. An inequality indicates a 
possible crror. 


upgrade set. All the alternate indexes that VSAM has 
been instructed to update whenever there is a change to 
the data component of the base cluster. 


uscr buffering. The use of a work arca in the processing 
program’s address space for an 1;O buffer; VSAM 
transmits the contents of a control interval between the 
work arca and direct access storage without 
intermediary buffering. 


uscr catalog. An optional catalog used in the same way 
as the master catalog and pointed to by the master 
catalog. It also lessens the contention for the master 
catalog and facilitates volume portability. 


vertical pointer. A pointer in an index record of a given 
level that gives the location of an index record in the 
next lower level or the location of a control interval in 
the data sct controlled by the index. 


virtual storage access method. An access method for 
direct or sequential processing of fixed and 
variable-length records on direct access devices. The 
records in a VSAM data set or file can be organized in 
logical sequence by a key ficld (key sequence), in the 
physical sequence in which they are written on the data 
set or file (entry sequence), or by relative record 
number. 


virtual telecommunications access method. <A set of 
programs that control communication between terminals 
and application programs running under VSE, OS VSI, 
and OS;VS2. 


VSAM. (See virtual storage access method.) 


VSAM resource pool. A virtual storage area that is 
used to share I/O buffers, 1/O-related control blocks, 
and channel programs among VSAM data sets. A 
resource pool is local or global; it serves tasks in one 
partition or address space or tasks in all address spaces 
in the system. 

VSAM shared information. Blocks that are used for 
cross-system sharing. 


VSI. (See VSAM shared information.) 
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| VTAM. (See virtual telecommunications access 
| method.) 
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in GENCB macro 72 
in TESTCB macro 147 


[>] 


DATA option 
BLDVRP macro 48 
data set attributes 
testing in TESTCB macro example 148 
DDN subparameter 
in MACRF parameter of the ACB macro 38 
DDNAME parameter 
in ACB macro 37 
in FIELDS parameter 135 
in GENCB macro 72 
deferring write requests 3 
delcting a record 
addressed-sequential deletion 64 
ERASE macro 63 
key-dircct delction 63 
DFR subparameter | 
in MACRF parameter of the ACB macro 38 
DINVALID subparameter 
in MRKBFR macro 106 
DIR subparameter 
in MACRF parameter of the ACB macro 38 
in OPTCD parameter of RPL macro 128 
direct processing 
reason code positioning state 25 
disconnecting your program 
CLOSE macro 55 
DLVRP macro 
example 60 
execute form 175 
format 59 
return codes 31 
summary 160 
DRBA subparamceter 
in WRTBFR macro = 157 
DS subparameter 
in WRTBFR macro 157 
DSN subparameter 
in MACRF parameter of the ACB macro 38 


LE] 


ECB parameter 
in FIELDS parameter 142 
in GENCB macro 82 
in RPL macro 127 

ECB subparameter 
CNVIFAD macro 58 
MRKBFR macro 106 
SCHBFR macro 132 


element entry 


in parameter lists of GENCB, MODCB, SHOWCB, 
and TESTCB macros 183 
coding example 185 
illustration 185 
ellipses, in notation convention vii 
end-of-volume 
return codes 31 
ENDRBA parameter 
in FIELDS parameter 136 
ENDREQ macro 
example 61 
format 61 
terminating a request 
summary 160 
used with WRTBEFR macro 156 
entry 
element, in parameter lists of GENCB, MODCB, 
SHOWCR, and TESTCB macros’ 183 
header, in parameter lists of GENCB, MODCB, 
SHOWCEB, and TESTCB macros’ 183 
entry-sequenced data sct 
used in ACQRANGE macro 44 
EODAD parameter 
in EXLST macro 66 
in GENCB macro 76 
in SHOWCB macro 139 
in TESTCB macro 150 
ERASE macro 
' deleting a record 
summary 160 
format 63 
ERASE processing 63 
ERET parameter 
in TESTCB macro 146, 150, 152 
error ficld of the ACB 
reason codes from OPEN macro 2 
ERROR parameter 
in FIELDS parameter 135 
ESDS parameter 
in TESTCB macro 146 
event control block 
used in ACQRANGE macro 45 
example 
addition of records, PUT macro 119 
addressed-sequential deletion, ERASE macro 64 
addressed-sequential retrieval, GET macro 89 
addressed-sequential update, PUT macro 123 


Index 199 


check return code after asynchronous request, suspend many record request, CHIECK macro 53 
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PUTIX macro 125 
RPL macro 126 
SCHIBFR macro 132 
SHOWCB macro 133 
TESTCB macro 145, 150 
VERIFY macro 155 
WRIBFR macro 156 
format of the parameter lists 183 
FS parameter 
in FIELDS parameter 136 
FTNCD parameter 
in FIELDS parameter 142 
in TESTCB macro 153 
FWD subparameter 
in OPTCD parameter of RPL macro 129 


GENCB macro 
execute form 175 
with parameter lists built by user 183, 185 
format 69 
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summary 162 
generate an access method control block at 
execution time 
summary 161 


gencrate an exit list at execution time 
summary 162 
generate form 176 
reentrant example 179 
generating a request parameter list 80 
generating a requcst parameter list example 85 
generating an access method control block 69 
generating an access method control block 
example 75 
generating an exit list 76 
gencrating an exit listexample 78 
inconsistent operand error 3 
linking to VSAM directly 187 
list form 175 
operand notation 181 
reason codes 10 
return codes 10 
generate form 
GENCB macro 176 
MODCB macro 176 
SHIOWCB macro 177 
TESTCB macro 178 
use of 178 
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gcncrating a request parameter list 
GENCB macro 80 
RPL macro 126 
generating an access method control block (GENCB 
macro) 69 
gencrating an exit list 
at assembly time 66 
GENCB macro 76 
GET macro 
format 86 
retricving a direct to sequential record example 94 
retricving a keyed-direct record 92 . 
retricving a keyed-sequential record (backward) 
example 
backward 87 
retrieving a record 
summary 162 
retrieving a relative record example 91 
retrieving a skip-sequential record, example 87 
retrieving an addressed-direct record example 93 
retricving an addressed-scquential record 
example 89 a 
retrieving keyed-scquential record example 
forward 86 
GETIX macro 
format 97 
retricving an index record 
summary 163 
GSR option 
BLDVRP macro 48 
in MACRF parameter of the ACB macro 39 
GSR subparameter 
DLVRP macro 59 
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HALCRBA parameter 
in FIELDS parameter 136 
header entry 
in parameter lists of GENCB, MODCB, SHOWCB, 
and TESTCB macros 
coding example 185 
illustration 185 
using macros to build 185 
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ICI subparameter 
in MACRF parameter of the ACB macro 38 
IDAELEM macro 185 
IDAGENC macro 185 
IDAMODC macro 185 
IDASHOW macro 185 
IDATEST macro 185 
IN subparameter 
in MACRF parameter of the ACB macro 38 
index 
retrieval (GETIX macro) 97 
storing (PUTIX macro 125. 
INDEX option 
BLDVRP macro 48 
indirect address for S-type address constant 33 
indirect S-type address constant 69 
inserting records 
keyed-direct 118 
keyed-sequential [11,115 
skip sequential 116 
1O parameter 
' in TESTCB macro 153 
IOPID parameter 
in EXLST macro 66 


JRNAD parameter 
in EXLST macro 67 
in GENCB macro 77 
in SHOWCB macro 140 
in TESTCB macro. 150 
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KEQ subparam¢eter : 

in OPTCD parameter of RPL macro 129 
KEY subparameter 

in MACRF parameter of the ACB macro 38 

in OPTCD parameter of RPL macro 128 
key-direct deletion 

example 63 
key-sequenced data set 

used in ACQRANGE macro 44 
KEYLEN parameter 

BLDVRP macro 47 

in FIELDS parameter 136, 143 

in GENCB macro 82 

in RPL macro” 127 
keywords 

execute form 173 

generate form 173 

list form 172 
KGE subparameter 

in OPFCD parameter of RPE. macro 130 
KSDS parameter 

in TESTCB macro 146 
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LDS parameter 

in TESTCB macro 146 
LENGTI parameter 

in GENCB macro 72, 77, 82 
tn SHIOWCB macro 133, 139, 141 
LERAD parameter 

in EXLST macro 67 

in GENCB macro 77 

in SHOWCB macro 140 

in TESTCB macro 150 
linear data set 

error in VERIFY macro 155 

logical error reason codes 23 
linking to VSAM directly 187 
list form 

BLDVRP macro 174 

GENCB macro 175 

MODCB macro 176 

SHOWCB macro 177 

TESTCB macro 177 

use of 178 
list-form keyword 172 
list, execute, generate formats 174 
list, execute, generate forms of macros 171 
list, parameter 

of GENCB, MODCB, SHOWCB, and TESTCB 

macros 183 

LOC parameter 

in GENCB macro 72, 77, 82 
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removal from the BLDVRP macro 47 
LOC subparameter 

in OPTCD parameter of RPL macro 130 
local shared resources 

ACB example 43 
locate mode 

with control interval access 

with shared resources 132 

lower case, in notation convention vii 
1.RD subparameter 

in OPTCD parameter of RPL macro 129 
LRECL parameter 

in FIELDS parameter 136 
LRU subparameter 

in WRTBFR macro 157 
LSR option 

BLDVRP macro 48 

DLVRP macro 59 

in MACRF parameter of the ACB macro 39 
LSR pool 

example in BLDVRP macro 50 
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MACRF parameter 
in ACB macro 37 
in GENCB macro 72 
in TESTCB macro 147 
macro instruction return codes and reason codes 
macros 
descriptions 1 
summary of 159 
MAREA parameter 
in ACB macro 40 
in FIELDS parameter 135 
in GENCB macro 73 
MARK parameter 
in MRKBFR macro 106 
marking records inactive 124 
message area 
~ header information .. 8 
message list 9 
OPEN/CLOSE 7 
provided by VSAM 7 
MLEN parameter 
in ACB macro 40 
in FIELDS parameter 135 
in GENCB macro 73 
MNTACQ macro 
format 98 
summary 163 
MODCB macro 
example 101 
execute form 176 
reentrant example 180 
with parameter lists built by user 183 
format 100 
generate form 176 
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linking to VSAM directly 187 
list form 176 
modify a request parameter list example 105 
modify an exit list example 103 
modifying a request parameter list 104 
summary 164 
modifying an ACB 100 
summary 163 
modifying an exit list 
format 102 
summary 163 
operand notation 181 
reason codes 10 
remote-list form 
recntrant example 179 
return codes 10 
MODE option 
BLDVRP macro 48 
MODE parameter 
DLVRP. macro 59 
in CLOSE macro 55 
in OPEN macro 107 
modifying and displaying the RECLEN ficld of an RPL 
directly 188 
move mode of control interval access 
with shared resources 132 
MRKBER macro 
format 106 
invalidating a buffer 
parameters for 106 
reason codes 106 
summary 164 
MSGAREA parameter 
in FIELDS parameter 143 
in GENCB macro 82 
in RPL macro 127 
MSGLEN parameter 
in FIELDS parameter 143 
sin GENCB macro 82 
in RPL macro 127 
MVE subparameter 
in OPTCD parameter of RPL macro 130 
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NCI subparameter 
in MACRF parameter of the ACB macro 38 
NCIS parameter 
in FIELDS parameter 136 
NDELR parameter 
in FIELDS parametcr 136 
NDF subparameter . 
in MACRF parameter of the ACB macro 38 
NEXCP parameter 
in FIELDS parameter 136 
NEXT parameter 
in FIELDS parameter 136 
NFX subparameter 
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NINSR parameter 

in FIELDS parameter 136 
NIS subparameter 

in MACRF parameter of the ACB macro 39 
NIXL parameter 

in FIELDS parameter 136 
NLOGR parameter 

in FIELDS parameter 136 
NO subparameter, in CATALOG parameter 

in ACB macro 36 

in GENCB macro 71 

in TESTCB macro 147 

restriction 36, 71 
NRETR parameter 

in FIELDS parameter 136 
NRM option 

in MACRF parameter of the ACB macro 39 
NRS option 

in MACRF parameter of the ACB macro 39 
NSP subparameter 

in OPTCD parameter of RPL macro 129 
NSR option 

in MACRF parameter of the ACB macro 39 
NSSS parameter ; 

in FIELDS parameter 136 
NUB option 

in MACRF parameter of the ACB macro 39 
NUIW parameter 

in FIELDS parameter 137 
NUP suhparameter 

in OPTCD parameter of RPL macro 129 
NUPDR parameter 

in FIELDS parameter 137 
NWAITX subparameter 

in OPTCD parameier of RPL macro 130 
NXTRPE parameter 

in FIELDS parameter 143 

in GENCB macro 83 

in RPL macro 128 
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OBJECT parameter 
in SHOWCB macro 134 
in TESTCB macro 146 
OFLAGS parameter 
in TESTCB macro 147 
OPEN macro 
connecting program and data 
summary 164 
format 107 
open two data sets example 108 
parameter list above 16M example 108 
reason codes 2 
use of SHOWCB macro 2 
use of VERIFY command 2 
return codes | 


shared resources 
reason codes 3 
OPEN;CLOSE message area for multiple 
reason/warning messages 7 

opening a data set 

for processing 107 
OPENOB3S parameter 

in TESTCB macro 148 
operand notation 

GENCB 181 

MODCB 181 

SHOWCB 181 


TESTCB 181 
operands 

optional 174 

required 174 


operands with GENCB, MODCB, SHOWCB, 
TESTCB 181 
OPTCD parameter 
in GENCB macro 83 
in RPL macro 128 
in TESTCB macro 153 
OPTCD subparameter 
ACQRANGE macro 44 
GETIX macro 97 
in RPL macro 130 
MNTACQ macro 98 
PUTIX macro 125 
SCHIBFR macro 132 
optional operands 174 
or sign, in. notation convention — vit. 
OUT subparameter 
in MACRF parameter of the ACB macro 39 
in MRKBFR macro 106 
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parameter list 


of GENCB, MODCB, SHOWCB, and TESTCB 


macros 183 
passing control directly to VSAM _ = 187 
PASSWD parameter 
in ACB macro 40 
in FIELDS parameter 135 
in GENCB macro 73 
physical error analysis 
with control interval access 26 
physical error message 
displayed in SHOWCB macro cxample 144 
format 30 
RBA ficld 26 
POINT macro 
format 109 
position example 109 
positioning for access 
summary 164 
positioning 
following logical errors 24 
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of reason codes 25 
positioning for access (POINT macro) 109 
PUT macro 
addressced-sequential update example 123 
format 111 
keyed-direct insertion example 118 
keyed-direct update example 121 
keyed-sequcential insertion example 111, 115 
keyed-sequential update example 120 
loading a relative record data sect 113 
marking records inactive example 124 
recording RBAs when loading example 112 
skip-sequential insertion example 116 
storing a record 
summary 164 
PUTIX macro 
format 125 
storing an index record 
summary 165 
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RBA field 
in physical error message 26 
RBA parameter 
in FIELDS parameter 143 
RBA values 
CNVTAD macro 58 
passed to MNTACQ macro 58 
reason codes 
from OPEN macro 2 
use of SHOWCB 2 
from request macros (GET, PUT, etc.) 
physical errors, control interval access 26 
in control block manipulation macros 10 
in GENCB macro 10 
in MODCB macro 10 
in SH}IOWCB macro 10 
in TESTCB macro 10 
logical errors 17 
physical errors 26 
positioning state 25 
request parameter list feedback area 13,15 
sharcd resources from OPEN macro 3 
successful request 15 
use of VERIFY command in OPEN macro 2 
RECLEN ficld (record length) of an RPL 
modifying and displaying 188 
RECLEN parameter 
in FIELDS parameter 143 
in GENCB macro 83 
in RPL macro 130 
record 
retrieval (GET macro) 86 
record length (RECLEN field) of an RPL 
modifying and displaying 188 
record management 
_ return codes and reason codes 13 


reentrant program 33 
register notation 33, 69 
relative record data set 
used in ACQRANGE macro 44 
relative record number 
used asakey 91 
releasing exclusive or shared control 
MRKBFR macro 106 
REPL parameter 
in TESTCB macro 147 
request macros 
CHECK 51 
ENDREQ 61 
ERASE 63 
GET 86 
physical reason codes from 26 
POINT 109 
PUT 111 
request parameter list 
chaining 81, 126 
chaining example 84 
chaining in GET macro 96 
chaining not allowed 
with SCHBFR macro 132 
with WRIEBFR macro 156 
changing 104 
component codes from component code ficld 
displaying ficlds in SHOWCB macro 141 
generating at assembly time 
gcnerating at exccution time 80 
generating with GENCB macro example 85 
modifying 104 
reason codes from feedback area 15 
testing in TESTCB macro 152 
testing in TESTCB macro example 154 
with the GENCB macro 81 
with the RPL macro 126 
required operands 174 
resource sharing 714 
retricving a record 
for deletion 64 
retrieving an index record 13 
return codes 
checking, example 51 
from asynchronous request 14 
from BLDVRP macro 30 
from CLOSE macro 6 
from DLVRP macro 31 
from end-of-volume 31 
from macros used to share resources 30 
from OPEN macro 1 
from RPL 13 
in control block manipulation macros 10 
in GENCB macro 10 
in MODCB macro 10 
in SHOWCB macro 10 
in TESTCB macro 10 
synchronous request 14 
return codes and reason codes from OPEN 1 
reusable data set 
specifying in ACB macro processing). 39 
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RKP parameter 
in FIELDS parameter 137 
RLS subparameter 
in MRKBFR macro 106 
RMODES31I parameter 
example in BLDVRP macro 49 
example in the GENCB macro 75 
in ACB macro 40, 43 
in BLDVRP macro 47 
in OPEN macro 107 
in the GENCB macro 73 
in the MODCB macro 100 
RPL component code 13 
RPL condition code 13, 15 
RPL feedback area 13 
RPL feedback word 13 
RPL macro 
example 131 
format 126 
generate a request parameter list at assembly time 
summary 165 
RPL operand 
RECLEN field (record length} 
modifying and displaying 188 
RPL parameter 
in ACQRANGE macro 44 
in BLK parameter in GENCB macro 81 
in CHECK macro 51 
in CNVTAD macro 57 
in ENDREQ macro 6l 
in ERASE macro 63 
in GET macro 86 
in GETIX macro 97 
in MNTACQ macro 98 
in MODCB macro 104 
in MRKBFR macro 106 
in POINT macro 109 
in PUT macro 111 
in PUTIX macro 125 
in SCHBFR macro 132 
in SHOWCB macro 141 
in TESTCB macro 152 
in VERIFY macro 155 
in WRTBFR macro 156 
MNTACQ macro 98 
RPL reason code 13 
RPL return code 13 
RPLLEN parameter 
in FIELDS parameter 143 
RRDS parameter 
in TESTCB macro 147 
RST subparameter . 
in MACRF parameter of the ACB macro 39 
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S-type address constant 33, 69 
SCHBFR macro 
summary. 165 
SCRA subparameter, in CRA parameter 
in ACB macro 36 
in GENCB macro 72 
in TESTCB macro 147 
restriction 36, 72 
search argument 
full key 131 
gencric (partial) key 129 
SEQ subparameter 
in MACRF parameter of the ACB macro 38 
in OPTCD parameter of RPL macro 128 
sequential insert strategy 
specified in ACB 38 
sequential processing 
reason code positioning state 25 
shared resource macros 
return codes 30 
shared resources 34 
SHAREOPTIONS 4 
incompatible with deferring write requests 3 
sharing 
control blocks 
based on DDNAME 34 
based on DSNAME 34 
parameter lists 178 
among BLDVRP, DLVRP, GENCB, MODCB, 
SHOWCRB, and TESTCB 171 
reentrant form 178 
SHOWCB macro 
as used with CLOSE macro return codes 6 
display an ACB example 137 
displaying a physical error message example 144 
displaying an access method control block 
example 137 
displaying an exit list address example 138 
displaying fields of a request parameter list 141 
summary 166 
displaying ficlds of an access method control 
summary 166 
displaying fields of an access method control 
block 133 
displaying fields of an exit list 139 
summary 166 
displaying the length of an exit example 140 
execute form 177 
with parameter lists built by user 183 
format 133 . 
generate form 177 
linking to VSAM directly 187 
list form 177 
operand notation 181 
reason codes 10 
reason codes from OPEN macro 2 
return codes 10 
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SHRPOOL parameter 

ACB macro 41 

BLDVRP macro 47 

DLVRP macro 59 

in GENCB macro 74 
SIS option 

in MACRF parameter of the ACB macro 39 
skip-sequential processing 

reason code positioning state 25 
SKP subparamcter 

in MACRF parameter of the ACB macro 38 

in OPTCD parameter of RPL macro 128 
SPAN parameter 

in TESTCB macro 147 
SSWD parameter 

in TESTCB macro 147 
STMST parameter 

in FIELDS parameter 137 
storage requirements, I/O buffers 36, 70 
storing a record (PUT macro) 111 
storing an index record 13 
string extension, dynamic 35, 38 
STRMAX parameter 

in FIELDS parameter 135 
STRNO parameter 

BLDVRP macro 48 

in ACB macro 41 

in FIELDS parameter 135 

in GENCB macro 74 
summary of macros 159 
suspending processing 

overlap processing 52 

request for many records 53 
SYN subparameter 

in OPTCD parameter of RPL macro 129, 130 
SYNAD exit routine 

physical error message 26 
SYNAD parameter 

in EXLST macro 67 

in GENCB macro 77 

in SHOWCB macro 140 

in TESTCB macro 150 
synchronizing end of data 

(VERIFY macro) 155 


- synchronous processing 


specified in MODCB macro 104 

specificd in RPL macro 130 
synchronous request 

return codes 14 


T (Gin TYPE parameter in CLOSE macro) 7 
temporary CLOSE macro 7 
terminating a request 

ENDREQ macro 61 
terminating a request before completion 62 
TESTCB macro 154 


execute form 178 
with parameter lists built by user 183 
format 145, 150 
generate form 178 
linking to VSAM directly 187 
list form 177 
operand notation 181 
reason codes 10 
return codes 10 
testing a ficld of a request parameter list 
summary 168 
testing a field of an access method control block 
summary 167 
testing a field of an exit list 150 
summary 168 
testing a request parameter list 152 
testing ficlds of an access method control 
block 145 
testing for data set attributes 148 
using a branch table 151 
testing a control block 
exit list 150 
request parameter list 152 
transaction ID 
writing related requests 157 
TRANSID parameter 
in FIELDS parameter 143 
in GENCB macro 83 | 
in RPL macro 130 
TRANSID subparameter 
SCIIBFR macro 132 
TRN subparameter 
in WRTBER macro = 157 
TYPE parameter 
BLDVRP macre 48 
DLVRP macro 59 
in CLOSE macro 7, 55 
in WRTBFR macro 156 


UBF option 

in MACRF parameter of the ACB macro 39 
UCRA subparameter, in CRA parameter 

in ACB macro 36 

in GENCB macro 72 

in TESTCB macro 147 

restrictions 36, 72 
UIW parameter 

in FIELDS parameter 137 
underlining, in notation convention vii 
UNQ attribute, in ATRB parameter 147 
UPAD parameter 

in EXLST macro 67 
UPD subparameter 

in OPTCD parameter of RPL macro 129 
updating records 
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See also storing a record, lengthening a record, and 
shortening a record 

addressed-sequential 123 

example 120 

keyed-direct 121 

keyed-sequential 120 
upgrade set 

status following request that fails 14 
upper case, in notation convention _ vii 
use of list, execute, generate forms 178 

,ouser buffering 39 
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VERIFY command . 
-use in OPEN macro” 
reason codes 2 
‘VERIFY macro 
“format 155 
“1, summary 168 
VSAM macro formats and examples 33 


WAITX subparameter 
"in OP TCD parameter of RPL macro 130 
WAREA parameter 
in GENCB 
generating request parameter list 83 
in GENCB macro 
generating access method control block 74 
generating exit list 74, 77 
WCK parameter 
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in TESTCB macro 147 
work area 
processing a recordin 83, 126 
relation to I/O buffer 83, 126 
specifying 
generating access method control block 74 
generating exit list 77 
generating request parameter list 83 
work data set 
specifying in ACB macro 39 
WRTBFR macro 
format 156 
summary 169 


XINVALID subparameter 
in MRKBFR macro 106 
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YES subparameter, in CATALOG parameter 
in ACB macro 36 
- in GENCB macro 71 
in TESTCB macro 147 
restriction 36, 71 
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ACB example 43 
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